bytedance/deer-flow 保姆级部署教程：字节开源的长程 SuperAgent 智能体框架

一句话定位：GitHub 开源项目 bytedance/deer-flow（DeerFlow，Deep Exploration and Efficient Research Flow）是字节跳动开源的一个SuperAgent 运行时（super agent harness）——在 LangGraph / LangChain 之上把「子智能体编排、长期记忆、沙箱执行、可扩展技能」打包成开箱即用的长程任务智能体，可研究、可编码、可创作。

slogan：An open-source super agent harness that orchestrates sub-agents, memory, and sandboxes to do almost anything — powered by extensible skills.

仓库地址：https://github.com/bytedance/deer-flow · 许可证：MIT · ⭐ 84,768 · 当前版本 2.0（从零重写版，1.x 旧版维护在 main-1.x 分支）

▲ 图 0：deer-flow 官方 README 顶部展示的 Python 3.12+、Node.js 22+、MIT License 三个 shields.io 徽章，以及 Trendshift 仓库趋势徽章（bytedance/deer-flow，官方仓库 README 截图）

一、项目简介

DeerFlow 最早是一个 Deep Research（深度研究）框架，社区把它一路用到了数据管道、幻灯片生成、仪表盘搭建、内容工作流自动化等远超「研究」范畴的场景。字节跳动团队据此判断：DeerFlow 的真正价值不是某个研究工具，而是一个harness（智能体运行时）——给智能体配齐文件系统、记忆、技能、沙箱感知执行、以及「规划并派发子智能体处理复杂多步任务」的基础设施。

于是 2026 年 2 月 2.0 版本发布，从零重写：不再是「你自己拼装」的框架，而是电池全配好、可二次开发的 SuperAgent harness。它构建在 LangChain 与 LangGraph 之上，内置文件系统、记忆、技能、沙箱感知执行和子智能体派发能力。2026 年 2 月 28 日，DeerFlow 2.0 登顶 GitHub Trending 日榜第一。

DeerFlow 的「技能（Skills）」是一组结构化能力模块——一个 Markdown 文件（SKILL.md）定义工作流、最佳实践与配套资源引用。官方内置了研究、报告生成、幻灯片制作、网页生成、图片与视频生成等技能；技能按需渐进加载，不会一次性塞满上下文窗口，对 token 敏感的模型也友好。你也可以替换内置技能、自定义新技能、或把它们组合成复合工作流。

姊妹项目 LLM Space 是 DeerFlow 背后的桌面调试工具，用来原型化智能体想法、检查每一步 harness 运行、回放失败与做性能基准。

▲ 图 1：DeerFlow 官方 README 中「Sister Projects」一节展示的姊妹项目 LLM Space 官方示意图（官方仓库 README 内嵌图，user-attachments 资源）

二、功能特点 / 核心能力

三、环境要求

• Python：3.12+（官方徽章标注）
• Node.js：22+，前端使用 pnpm（通过 corepack 自动启用，无需全局装 pnpm）
• Docker（推荐生产部署）：Docker Desktop / Docker Engine + Docker Compose v2.24+（旧版 Compose 无法解析 docker/docker-compose.yaml 里的可选 env_file 语法）
• 本地开发：需要 uv（Python 包管理）、nginx（本地反向代理）；Windows 下请用 Git Bash，原生 cmd / PowerShell 不支持仓库里的 bash 脚本，WSL 不保证可用
• 硬件起步配置：
  • 本地评估 / make dev：起步 4 vCPU / 8 GB RAM / 20 GB SSD，推荐 8 vCPU / 16 GB RAM（2 vCPU / 4 GB 通常不够）
  • Docker 开发 / make docker-start：起步 4 vCPU / 8 GB RAM / 25 GB SSD，推荐 8 vCPU / 16 GB RAM
  • 长跑服务器 / make up：起步 8 vCPU / 16 GB RAM / 40 GB SSD，推荐 16 vCPU / 32 GB RAM
• 操作系统：Linux + Docker 是推荐的持久化部署目标；macOS / Windows 建议仅作开发或评估环境
• LLM 服务：需要至少一个模型提供商的 API Key（官方推荐 Doubao-Seed-2.0-Code、DeepSeek v3.2、Kimi 2.5）；如要自托管本地 LLM，硬件需单独规划

四、保姆级部署步骤

4.1 拉取仓库

从 GitHub 仓库 克隆：

git clone <仓库地址>
cd deer-flow

4.2 交互式配置向导（约 2 分钟）

在仓库根目录执行：

make setup

向导会引导你选择 LLM 提供商、可选的网页搜索、以及执行/安全偏好（沙箱模式、bash 访问、文件写入工具等），自动生成最小化的 config.yaml 并把密钥写入 .env。你也可以在这里跳过搜索提供商，以后再补。

如果想直接手工改配置：

make config   # 复制完整模板到 config.yaml

随时可以跑一次体检：

make doctor   # 校验配置并给出可操作的修复提示

4.3 方式一：Docker 生产部署（官方推荐）

确认 Compose 版本满足要求：

docker compose version

一键构建并启动全部生产服务（构建镜像、挂载运行时配置与数据）：

make up

make up 会等待 Gateway 的 /health 端点就绪后才报告成功；若启动窗口内 Gateway 未健康，会非零退出并打印容器状态与最近的 Gateway 日志。

访问地址：http://localhost:2026

停止 / 重启：

make down        # 停止并移除容器

开发模式（热重载、源码挂载）：

make docker-init     # 拉取沙箱镜像（仅首次或镜像更新时）
make docker-start    # 启动服务（根据 config.yaml 自动探测沙箱模式）
make docker-logs     # 查看日志

分两步构建（先构建、后启动）：

./scripts/deploy.sh build    # 构建全部镜像
./scripts/deploy.sh start    # 启动已构建镜像
./scripts/deploy.sh down     # 停止

Linux 权限提示：如果 Docker 命令报 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock，把当前用户加入 docker 组并重新登录后重试。

PyPI 镜像提示：Gateway 镜像用 uv sync --locked 安装，uv.lock 锁定了 pypi.org/simple。不要在构建时把 UV_INDEX_URL 换成清华镜像等，否则会因为 lockfile 校验失败；前端 pnpm 可用独立的 NPM_REGISTRY 指向 registry.npmmirror.com。

4.4 方式二：本地开发（不用 Docker）

前提：先完成 4.2 的 make setup，仓库根目录有可用的 config.yaml。

① 检查前置依赖（Node 22+、pnpm、uv、nginx）：

make check

② 安装后端 + 前端依赖 + pre-commit hooks：

make install

③（可选）预拉沙箱镜像：

make setup-sandbox

④ 启动服务：

make dev

⑤ 访问 http://localhost:2026。本地服务固定使用内部端口 8001（Gateway）、3000（Next.js）、2026（nginx 入口），根目录 .env 里的 PORT 只影响 Docker 入口。

冷启动较慢时可放宽等待时间：

DEER_FLOW_GATEWAY_STARTUP_TIMEOUT=240 make dev

停止：

make stop

4.5 终端 TUI（最轻量）

如果你只想要一个终端里的智能体工作台，不跑 Web / nginx / Docker，可以直接装 Python 包内嵌 TUI：

uv pip install 'deerflow-harness[tui]'

deerflow                                      # 启动终端 UI（需 TTY）
deerflow --tui-transparent                    # 用终端默认背景
deerflow --continue                           # 恢复最近一个线程
deerflow --resume THREAD_ID                   # 按 id 恢复线程
deerflow --print "总结这个仓库"               # 无头一次性输出到 stdout
deerflow --json  "hello"                      # 无头换行分隔 StreamEvents

TUI 与 Web UI 共享同一份线程存储，在终端里开的会话会出现在 Web 侧栏里。

五、配置说明

• 模型接入：管理后台打开 Settings → Models，选一个 provider 填入 API Key 与 model ID 即可，端点、鉴权、adapter 都由后端预置（OpenAI、Anthropic、DeepSeek、阿里百炼、火山引擎/豆包、Moonshot/Kimi、智谱、MiniMax）；也支持自定义 OpenAI 兼容 base URL。新建模型即时生效，无需改 YAML 或重启 Gateway。
• 手工 YAML：config.example.yaml 是完整参考，包含 CLI 后端（Codex CLI、Claude Code OAuth）、OpenRouter、Responses API、子智能体并发上限 subagents.max_total_per_run 等。YAML 中的模型在 Web 管理页只读。
• 密钥存储：托管模型目录存放在 $DEER_FLOW_HOME/managed-models/（默认 .deer-flow/managed-models/），请整目录备份并收紧文件权限；丢失本地加密密钥需要从备份恢复。
• 沙箱模式：在 config.yaml 里选择 sandbox.use：本地执行（直接在宿主跑）、Docker 执行（隔离容器）、Kubernetes provisioner（通过 provisioner 服务）。
• 网页搜索：向导里可选 Brave / GroundRoute / DuckDuckGo / Tavily / Sofya / Serper / SearXNG / InfoQuest / Tencent WSA / Serply 等多个提供商。
• 运行时路径：运行时数据默认在项目根下 .deer-flow/，可用 DEER_FLOW_HOME 迁移；技能默认在项目根 skills/，可用 DEER_FLOW_SKILLS_PATH 迁移。

六、使用方法

6.1 一句话交给 Coding Agent 自动装

如果你用 Claude Code、Codex、Cursor、Windsurf 或其他编码智能体，直接给它一句话（其中的 Install.md 链接见文末「相关链接」）：

Help me clone DeerFlow if needed, then bootstrap it for local development by following the Install.md URL.

它会自动判断是否需要 clone、有 Docker 就走 Docker、并在缺配置时停下问你要下一条命令。Install.md 原始链接见文末相关链接一节。

6.2 Web 工作台

启动后打开 http://localhost:2026，首次进入创建本地账号（密码至少 8 位）。在工作区侧栏打开 Capability Center 管理 Plugins（MCP servers、飞书集成）与 Skills；在 Settings → Models 选好模型后即可开始对话。复杂任务主智能体会自动拆成子任务并派发子智能体执行，完成后把报告、引用、产物文件一并交付。

6.3 LangGraph Studio（可选开发调试）

默认 make dev 使用 Gateway 内嵌运行时，不需要 LangGraph Studio。想单独看 lead-agent 图：

cd backend
uv run langgraph dev --allow-blocking

命令会打印本地 API 与 Studio UI 地址；该内存服务器仅用于开发测试，不能当生产用。

6.4 提交 Issue 前收集诊断包

make support-bundle

会在 .deer-flow/support-bundles/ 下生成 *-issue-summary.md（粘贴用）、*-issue-draft.md（AI 辅助提单）与可选证据 zip；不会包含 .env、原始对话或用户文件内容。

七、常见问题 FAQ

问一：DeerFlow 2.0 和 1.x 是什么关系？我的旧 Deep Research 配置还能用吗？
答：2.0 是从零重写，与 v1 不共享代码。旧的 Deep Research 框架仍维护在 main-1.x 分支，欢迎继续贡献；新的活跃开发全部在 2.0。如果你只想用原来的 Deep Research 能力，请到 1.x 分支。

问二：Docker 构建失败，报 lockfile needs to be updated？
答：因为你在构建时把 UV_INDEX_URL 换成了 PyPI 镜像。Gateway 镜像用 uv sync --locked 严格校验 uv.lock，请保持默认的 pypi.org/simple。前端 pnpm 可以单独走 NPM_REGISTRY 指向 registry.npmmirror.com，两者互不影响。

问三：make up 报告 runtime home 不可写或 secret 不可读？
答：按脚本打印的 sudo chown -R <uid>:<gid> '<home>' 命令修复后重试即可；make down 不需要读 secret，随时可用。

问四：本地冷启动 Gateway 端口起不来，make dev 超时？
答：先看 logs/gateway.log 找启动报错；确认是冷启动慢后放宽等待时间：DEER_FLOW_GATEWAY_STARTUP_TIMEOUT=240 make dev（单位秒，正整数），也可以写在根目录 .env 里。

问五：生产环境能不能开多 worker 提高并发？
答：生产默认 GATEWAY_WORKERS=1，因为 Gateway 进程内持有正在跑的 run 任务。多 worker 需要同时满足：Postgres 数据库、stream_bridge.type: redis、run_ownership.heartbeat_enabled: true、run_events.backend: db，并共享 DEER_FLOW_CREDENTIALS_KEY。Kubernetes 上每个 Pod 一个 worker，需要声明 deployment.multi_instance: true。

▲ 图 2：DeerFlow 官方 README 「Terminal Workbench (TUI)」一节内嵌的终端工作台预览图（仓库 docs/tui/tui-preview.svg 官方 SVG）

相关链接

• 项目仓库：bytedance/deer-flow
• 官方网站（含真实 Demo）：https://deerflow.tech
• 1.x 旧版分支（Deep Research 框架维护中）：main-1.x
• 姊妹项目 LLM Space：deer-flow/llm-space
• 配置完整参考：backend/docs/CONFIGURATION.md
• TUI 完整指南：backend/docs/TUI.md
• 安装引导脚本：Install.md
• 火山引擎 Coding Plan（官方推荐模型套餐）：中国大陆活动页
• Star History 趋势：bytedance/deer-flow 星标历史

▲ 图 3：DeerFlow 官方 README 末尾「Star History」一节展示的 bytedance/deer-flow 星标历史趋势图（star-history.dera.page 官方徽章）