deer-flow 详细介绍：开源项目架构、功能与实践指南

项目快照：bytedance/deer-flow，约 80,123 个 Star，10,971 个 Fork；最新推送时间 2026-08-17T00:47:39Z。本文基于仓库公开资料撰写。

项目地址：https://github.com/bytedance/deer-flow · https://deerflow.tech

deer-flow 从代码、运行环境到实践流程的项目封面 — deer-flow 的项目能力与实践流程示意。

项目速览（TL;DR）

deer-flow 是字节跳动开源的长时任务超级智能体框架（SuperAgent harness）。仓库描述显示，它通过沙箱、记忆、工具、技能、子智能体和消息网关，处理持续时间从数分钟到数小时不等的研究、编程和内容创建任务。

根据提供的 GitHub 仓库元信息，项目当前默认分支为 main，主要语言为 Python，许可证为 MIT，仓库记录的 Star 数为 80123，Fork 数为 10971。README 标注 DeerFlow 2.0 使用 Python 3.12 及以上版本、Node.js 22 及以上版本，并明确说明 2.0 是从头重写的版本，与 1.x 不共享代码。

DeerFlow is an open-source super agent harness that orchestrates sub-agents, memory, and sandboxes to do almost anything — powered by extensible skills.
来源：README

定位与目标用户

DeerFlow 的重点不是提供单一问答接口，而是为需要长时间执行、工具调用、上下文管理和文件操作的任务提供编排层。任务可以由主智能体拆解，再交给子智能体、搜索工具、沙箱或技能模块执行，最终汇总为可交付结果。

它的目标用户包括需要构建研究型智能体、代码型智能体、自动化内容生产流程以及内部任务处理系统的工程团队。由于项目同时涉及模型供应商、执行权限、外部搜索、消息通道和可观测性配置，使用者需要具备本地服务部署、密钥管理和运行时故障排查能力。

适用的任务形态

需要多轮检索、整理资料并生成结构化结果的研究任务。
需要读取或写入工作目录、执行代码并持续维护上下文的编程任务。
需要把复杂目标拆分为多个阶段，并由子智能体分别处理的长时任务。
需要通过消息网关接入飞书、Slack、Telegram、Discord、企业微信或钉钉等通道的自动化流程；具体可用能力取决于配置项和对应凭据。

核心功能

核心能力围绕“任务编排”展开，而不是简单增加模型调用次数。README 将子智能体、记忆、沙箱、技能、工具、上下文工程和消息通道列为 2.0 的重要组成部分，实际运行结果还取决于模型供应商、外部服务密钥以及安全配置。

技能与工具

技能（Skills）是可扩展的任务能力单元，工具（Tools）则负责向智能体提供搜索、抓取、文件处理或其他外部操作入口。一个任务通常由模型先判断需要哪些工具，再产生工具调用；工具返回结果后，模型继续推进任务，最终输出文本、文件或其他会话结果。

README 列出 Serper、Tavily、Jina、InfoQuest，并将 Firecrawl 标记为可选环境变量。未配置对应密钥时，README 没有承诺相关在线搜索或抓取能力仍可用，因此不应把这些服务视为默认内置数据源。

子智能体

子智能体（Sub-agents）用于把复杂目标拆分为相互独立或阶段性依赖的工作单元。主智能体负责规划和协调，子智能体负责执行被分配的研究、编码或分析任务，结果再回传给上层流程。

README 的配置说明提到 subagents.max_total_per_run，但提供资料没有给出该字段的默认值、完整类型说明或精确调度算法。部署时应以仓库中的 config.example.yaml 和最新 README 为准，不能根据字段名称推断具体并发行为。

沙箱与文件系统

沙箱（Sandbox）为智能体执行代码、命令和文件操作提供隔离边界。根据 README，安装向导会让使用者选择沙箱模式、Bash 访问权限和文件写入工具；项目还提供 E2B 沙箱以及 provisioner/Kubernetes 沙箱相关配置入口。

沙箱不是对所有风险的自动消除。若开放 Bash、文件写入或联网工具，模型生成的操作仍可能影响沙箱中的文件、进程和外部服务。生产部署需要根据数据敏感性、网络边界和凭据权限设置最小化授权。

记忆与上下文工程

记忆（Memory）用于在当前任务或更长生命周期中保留可复用信息，上下文工程（Context Engineering）则负责控制哪些历史消息、工具结果和中间产物进入模型上下文。README 将长期记忆、手动上下文压缩和上下文工程列为核心特性。

这意味着长时任务不必无限累积全部原始消息，而可以在需要时压缩上下文并保留任务重点。不过，资料没有给出记忆后端、清理策略、容量上限或持久化格式；涉及个人数据、源代码或内部文档时，应在上线前自行验证保存范围和删除机制。

消息网关与多通道接入

消息网关（Message Gateway）负责把外部消息通道与 DeerFlow 的会话和任务执行流程连接起来。提供的环境变量示例包含飞书、Slack、Telegram、Discord、企业微信和钉钉的凭据字段，但没有给出每个通道的完整回调协议、权限清单或事件重试语义。

因此，消息通道的接入应先在测试租户或测试机器人中验证。不要把生产机器人令牌直接写入仓库、公开日志或支持包中。

系统架构与关键模块

从 README 的功能描述和环境变量命名看，DeerFlow 2.0 可以按“前端或消息入口—网关—智能体编排—工具与子智能体—沙箱及持久化—观测”的逻辑链路理解。资料没有提供完整架构图、进程拓扑或模块级 API，因此下面只描述可由资料支持的职责边界。

逻辑执行链路

用户通过 Web 界面、嵌入式 Python 客户端或已配置的消息通道提交任务。
网关接收会话请求，并将其交给智能体运行时。
主智能体结合模型、记忆和上下文决定是否调用技能、工具或子智能体。
需要执行代码、Bash 或文件操作时，任务进入已配置的沙箱或执行环境。
工具和子智能体返回中间结果，主智能体继续规划，必要时进行上下文压缩。
任务结果通过会话界面、消息通道或文件形式返回。

模型提供商层

配置模板支持多个模型提供商，并允许使用 OpenAI、OpenRouter、Gemini、DeepSeek、Volcengine、Novita、MiniMax、StepFun、vLLM 等相关凭据或适配器。README 还提到 Codex CLI、Claude Code OAuth、Responses API，以及基于 CLI 订阅登录的模型提供方式。

模型层决定工具调用能力、上下文长度、代码执行质量和成本估算结果。README 建议使用 Doubao-Seed-2.0-Code、DeepSeek v3.2 和 Kimi 2.5 运行 DeerFlow，但资料没有提供基准测试、吞吐量、延迟或成功率数据，不能据此推导性能承诺。

网关、前端与内部通信

.env.example 提到 Next.js 服务端渲染（SSR）通过 DEER_FLOW_INTERNAL_GATEWAY_BASE_URL 访问 Gateway，并列出默认值 http://localhost:8001。同时，Docker 统一入口的示例地址为 http://localhost:2026，内部部署还涉及 DEER_FLOW_TRUSTED_ORIGINS 和共享内部认证令牌。

这些地址分别对应前端服务端到网关的内部连接，以及统一入口或端口转发场景。资料未提供完整端口映射表和生产拓扑，跨主机、容器服务名或反向代理部署时，应以仓库 Docker 配置和当前文档为准。

依赖与运行环境

README 的徽章明确要求 Python 3.12+ 和 Node.js 22+。项目根目录使用 Makefile 提供安装、配置和诊断入口；README 没有在提供资料中列出完整 Python 包清单、Node.js 包清单或锁文件内容，因此不能补写未核实的依赖版本。

Python：3.12 及以上。
Node.js：22 及以上。
容器运行：README 将 Docker 列为推荐运行选项，但提供片段没有列出 Docker Engine 或 Compose 的版本要求。
模型服务：至少需要在配置中选择模型提供商，并按供应商要求准备凭据。
搜索与抓取：Serper、Tavily、Jina、InfoQuest 等服务需要相应 API Key；README 将 Firecrawl 标为可选。

如果本地环境不满足上述版本要求，官方仓库未提供兼容性矩阵或降级方案，建议以最新 README 和仓库中的构建文件为准。不要仅凭 Python 作为主要语言就跳过 Node.js 环境检查，因为 README 同时明确标注了 Node.js 22+。

快速开始

快速开始的最小闭环是：克隆仓库、运行安装向导、完成模型配置、启动服务并执行诊断。下面的命令均来自 README 或其配置说明，示例限定在本地环境使用。

安装：克隆并运行安装向导

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

make setup 会启动交互式向导，用于选择 LLM 提供商、可选的 Web 搜索，以及沙箱模式、Bash 访问和文件写入等执行与安全选项。README 说明该向导会生成最小化的 config.yaml，并把密钥写入 .env；输入密钥时应使用测试环境凭据或权限受限的凭据。

运行：启动本地部署

make up

提供的资料在 .env.example 注释中明确提到 make up 会生成并持久化多工作进程部署所需的内部网关认证令牌。README 的目录把 Docker 作为推荐运行方式，但给定片段没有展开 make up 的完整服务列表、健康检查地址或日志命令；如果该命令在当前检出版本中有差异，应以仓库 Makefile 和最新 README 为准。

验证：检查配置和环境

make doctor

make doctor 用于验证安装设置并提供可操作的修复提示。它适合作为启动后的第一项验证，不等同于业务任务成功测试；模型调用、搜索服务、沙箱权限和消息通道仍需在授权的本地测试任务中分别验证。

配置说明

配置分为交互式生成和手工编辑两条路径。README 推荐使用 make setup，也允许使用 make config 复制完整模板，再参考 config.example.yaml 进行调整。

环境变量对照表

下表只列出资料中明确出现的环境变量。默认值采用 .env.example 或 README 直接给出的值；没有明确默认值的字段标记为“未提供”，不根据名称推断默认行为。

字段名	类型	默认值	作用
`SERPER_API_KEY`	字符串	未提供	配置 Serper Google Search 服务的 API Key。
`TAVILY_API_KEY`	字符串	未提供	配置 Tavily 搜索服务的 API Key。
`JINA_API_KEY`	字符串	未提供	配置 Jina 服务的 API Key。
`INFOQUEST_API_KEY`	字符串	未提供	配置 InfoQuest 的 API Key。
`BIND_HOST`	字符串	`127.0.0.1`	控制 Docker 栈入口绑定的主机接口。
`PORT`	整数	`2026`	控制 Docker 栈入口端口。
`GATEWAY_CORS_ORIGINS`	逗号分隔字符串	未设置	为拆分来源或端口转发部署配置精确的浏览器 CORS 来源白名单。
`E2B_API_KEY`	字符串	未提供	仅在使用 E2BSandboxProvider 时配置 E2B 云沙箱 API Key。
`LANGSMITH_TRACING`	布尔字符串	未设置	启用 LangSmith 对模型调用、智能体运行和工具执行的追踪。
`GATEWAY_ENABLE_DOCS`	字符串	未提供	设置为 `false` 时，在生产环境禁用 Swagger UI、ReDoc 和 OpenAPI Schema。

模型与密钥配置

模型配置可以通过安装向导完成，也可以编辑生成的 config.yaml。README 给出的手工配置示例包含 models 列表、模型名称、显示名称、use、具体模型名和 API Key 引用方式。

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

上面的示例来自 README，使用了 OPENAI_API_KEY 引用。真实部署时，应把 $OPENAI_API_KEY 对应的值放在本地 .env 中，而不是把真实令牌写入 YAML、提交记录或问题反馈。

网络入口与跨来源访问

BIND_HOST 默认绑定 127.0.0.1，README 将其描述为与本地可信环境匹配的部署模型。只有在自有 TLS、认证前门或防火墙保护下，才应考虑把它设置为 0.0.0.0；资料明确要求先完成首次设置，再让服务对外可达。

统一 Nginx 入口示例为 http://localhost:2026。如果前端和网关分属不同主机、容器或端口，需要检查 GATEWAY_CORS_ORIGINS、DEER_FLOW_INTERNAL_GATEWAY_BASE_URL 和 DEER_FLOW_TRUSTED_ORIGINS 的一致性。

进阶用法

进阶能力适合已经完成本地单任务验证的团队。每项能力都会扩大外部依赖、权限范围或运行链路，建议逐项开启，而不是在首次部署时同时启用全部通道。

沙箱模式选择

安装向导会询问沙箱模式，也会询问 Bash 和文件写入权限。资料明确列出 E2B 云沙箱 API Key，以及 provisioner/Kubernetes 沙箱的认证配置，但没有提供各模式的资源规格、网络策略或隔离强度对比。

本地试验可以先关闭不需要的高风险执行能力，只保留模型和文本处理路径。若必须执行代码，应将工作目录、网络访问和凭据范围限定在测试环境，并单独验证任务失败、超时和清理行为。

MCP Server 与技能扩展

MCP Server（Model Context Protocol Server）出现在 README 的高级功能目录中，技能系统也被定义为可扩展能力来源。提供的资料没有给出 MCP Server 的启动命令、配置格式、传输协议细节或权限模型，因此本文不提供未经核验的服务器示例。

可核查的配置入口是 config.example.yaml 和仓库文档。扩展技能时，应先确认工具输入是否经过校验、是否允许联网、是否能访问宿主机文件，以及错误结果是否会被模型继续使用。

IM Channels

README 的高级目录包含 IM Channels，环境变量示例列出了多种消息平台的机器人或应用凭据。配置完成后，外部消息可以进入 DeerFlow 的任务处理链路，但资料没有说明每个平台的消息格式和事件回调实现。

上线前应至少验证身份校验、重复事件、消息大小、附件处理、失败重试和敏感信息脱敏。对于企业内部机器人，建议使用专门的测试群或测试应用，避免把自动执行能力直接暴露给无关人员。

定时任务与终端工作台

README 的功能目录列出了 Scheduled Tasks 和 Terminal Workbench（TUI），说明项目包含定时任务和终端工作台方向的功能入口。给定资料未提供具体配置字段、命令、调度器实现、任务持久化方式或终端操作手册。

因此，涉及定时执行时应先确认任务是否会自动调用搜索、Bash、文件写入或外部消息通道。对于会产生外部副作用的任务，必须设置明确的运行身份、数据目录和人工审核边界。

可观测性与运维

DeerFlow 提供多种追踪入口，重点是观察模型调用、智能体运行和工具执行，而不是仅记录最终答案。可观测性配置应与密钥保护、会话脱敏和日志保留策略同时设计。

追踪后端

.env.example 明确列出了 LangSmith 的追踪变量，包括 LANGSMITH_TRACING、LANGSMITH_ENDPOINT、LANGSMITH_API_KEY 和 LANGSMITH_PROJECT。README 目录还列出 Langfuse Tracing 和 Monocle Tracing，但提供资料没有给出它们的变量清单。

启用追踪后，工具输入、模型提示词、文件路径或会话内容是否被发送到外部观测系统，需要依据具体集成配置确认。涉及未公开代码、个人信息或内部文档时，应在组织的数据处理规则下决定是否开启。

诊断与支持包

安装或运行异常时，先运行 make doctor 获取修复提示。若需要提交 GitHub Issue，README 建议运行 make support-bundle，该命令会生成问题摘要、AI 辅助问题草稿、可选证据压缩包，并提供 triage.json 供维护者或分诊工具使用。

README 特别说明，支持包包含脱敏诊断和文件清单，不包含 .env、原始对话消息或用户文件内容；压缩包只有在维护者要求或摘要不足以定位问题时才应附上。提交前仍应人工检查生成文件和路径信息，不能把“自动脱敏”视为无需复核。

数据库与多工作进程

当 config.yaml 中设置 database.backend: postgres 时，.env.example 要求配置 DATABASE_URL。资料还提到多工作进程部署需要共享的 DEER_FLOW_INTERNAL_AUTH_TOKEN，并说明 make up 会自动生成和持久化该令牌。

资料没有给出数据库迁移命令、连接池参数、备份策略或多工作进程的容量数据。生产运维方案应补充这些验证项，并以当前仓库的数据库和部署文档为准。

安全与合规边界

DeerFlow 能够调用搜索、抓取、Bash、文件写入和消息通道，因此安全边界取决于部署者授予的权限。所有操作都应限定在获得授权的本地、测试或组织内部环境中，不应把它用于未授权目标的数据采集、代码执行或账号操作。

凭据管理

API Key、机器人令牌、数据库连接串和 OAuth 凭据只应放在本地环境变量或受控密钥系统中，不应提交到 Git 仓库。
Claude Code 或 Codex CLI 订阅凭据应优先通过环境变量传递；README 提醒不要为了复用登录状态而直接挂载整个配置目录。
使用 CLAUDE_CODE_CREDENTIALS_PATH 时，资料说明它指向单个 .credentials.json 文件，而不是整个目录。
Provisioner/Kubernetes 沙箱需要配置 PROVISIONER_API_KEY，并保证 provisioner 容器与 config.yaml 中的值一致。

网络和执行隔离

默认 BIND_HOST=127.0.0.1 有助于维持本地可信环境边界。把绑定地址改为 0.0.0.0 前，应先完成首次设置，并配置自有 TLS、认证前门或防火墙；README 没有为 DeerFlow 提供内置的生产身份认证或公网安全承诺。

搜索和抓取功能还会把请求发送到外部服务，模型和工具输出也可能包含敏感信息。使用第三方搜索、追踪或模型服务前，应核对组织的数据出境、保留期限、供应商条款和授权范围。

文档端点与跨来源策略

GATEWAY_ENABLE_DOCS=false 可用于在生产环境禁用 Swagger UI、ReDoc 和 OpenAPI Schema。拆分前端与网关时，应通过 GATEWAY_CORS_ORIGINS 设置精确来源，不应把来源白名单扩大到不必要的范围。

项目具备代码执行和网络访问相关能力，安全评估应覆盖提示注入、恶意工具参数、文件越权、凭据泄露、日志泄露和外部消息误发。这里仅讨论授权环境下的防护与隔离，不提供针对未授权目标的攻击教程或绕过检测技巧。

许可证与商用条款

DeerFlow 本身采用 MIT，并不自动覆盖外部模型、搜索服务、消息平台、沙箱服务或其他依赖的条款。商业使用前，应分别审查这些服务的许可、API 使用限制、数据处理条款和费用规则。

局限性与已知限制

提供资料足以确认功能方向和安装入口，但不足以建立完整的生产级能力矩阵。以下限制是资料中明确缺失或需要额外核验的部分，不应被解释为项目缺陷清单。

官方仓库未提供该信息：完整架构图、模块 API、调用协议和稳定性承诺。
官方仓库未提供该信息：并发数、任务规模、延迟、吞吐量、成本或 Benchmark 数据。
官方仓库未提供该信息：不同沙箱模式的资源上限、隔离级别、网络策略和清理保证。
官方仓库未提供该信息：所有消息平台的回调格式、重试规则和权限清单。
官方仓库未提供该信息：数据库迁移、备份、恢复和高可用运维流程。
README 明确说明 2.0 与 1.x 不共享代码；需要原始 Deep Research 框架时，应查看仓库的 main-1.x 分支，而不是假定 2.0 可以直接兼容 1.x 扩展。

根据本文作者的经验判断，DeerFlow 的复杂度主要来自运行时组合，而非单个安装命令：模型、工具、子智能体、沙箱和外部通道任一环节配置不完整，都可能导致任务链路无法闭环。上线前应以小范围、可回滚的测试任务验证每个依赖。

适合谁

以下信号同时满足较多时，DeerFlow 的长时任务编排能力更有使用价值。判断重点是任务流程和运维条件，而不是仓库 Star 数。

团队需要处理持续数分钟到数小时的研究、编程或内容创建任务，而不是只处理单轮问答。
已有 Python 3.12+、Node.js 22+ 环境，并能维护本地 Docker 或对应服务运行环境。
任务需要搜索、文件操作、代码执行、记忆或子智能体协作，并且团队能够明确每项权限边界。
团队能够准备模型和外部工具凭据，并能负责密钥轮换、日志审计和失败任务排查。
希望在开源 MIT 项目基础上进行技能、模型提供商或消息通道扩展，并愿意自行核验第三方服务条款。

不适合谁

以下情况说明 DeerFlow 可能不是当前阶段的合适选择，或者至少不应直接进入生产环境。替代方案的具体选择不在提供资料范围内，应根据现有技术栈和合规要求另行评估。

只能运行低于 Python 3.12 或 Node.js 22 的固定环境，且无法升级运行时。
任务不需要工具调用、长上下文、文件处理或多阶段编排，只需简单的同步文本生成。
组织禁止向外部模型、搜索服务或追踪服务发送任务数据，且无法部署满足要求的内部替代服务。
团队没有人员管理沙箱、网关、消息凭据、数据库和运行日志，不具备故障恢复能力。
需要仓库已声明的 SLA、性能基准、完整企业支持或现成合规认证；提供资料没有这些承诺。

常见问题与排查（FAQ / Troubleshooting）

排查应先区分安装问题、模型配置问题、工具依赖问题和执行权限问题。使用仓库提供的诊断命令收集信息，比直接修改多个配置项更容易定位原因。

Q：首次安装应修改哪些文件？

A：推荐先执行 make setup，由向导生成最小化的 config.yaml 并写入 .env。需要完整模板时执行 make config，再参考 config.example.yaml；不要把真实密钥提交到版本库。

Q：为什么搜索工具无法工作？

A：先确认是否选择了搜索提供商，再检查对应的 SERPER_API_KEY、TAVILY_API_KEY、JINA_API_KEY 或 INFOQUEST_API_KEY。README 允许在安装向导中跳过 Web 搜索，因此未配置搜索服务时，不能假定在线检索已启用。

Q：如何确认本地设置是否正确？

A：运行 make doctor。该命令由 README 指定用于验证设置并给出修复提示；如果问题仍无法定位，可运行 make support-bundle，按 README 的说明审查生成摘要和证据文件后再提交 Issue。

Q：为什么不建议直接把服务绑定到公网？

A：.env.example 将 127.0.0.1 作为默认绑定地址，并要求只有在自有 TLS、认证前门或防火墙保护下才考虑使用 0.0.0.0。DeerFlow 具备执行命令、写文件和调用外部服务的能力，暴露入口前必须完成授权、认证和隔离设计。

Q：如何使用 Claude Code 或 Codex CLI 的登录状态？

A：资料列出了 CLAUDE_CODE_OAUTH_TOKEN、ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_CREDENTIALS_PATH 和 CODEX_AUTH_PATH 等可选变量，并建议优先通过环境变量传递令牌。是否需要目录挂载取决于适配器，README 提到 docker-compose.cli-auth.yaml 是目录挂载的可选回退方式。

Q：如何判断是否支持某个模型或服务？

A：检查仓库当前的 config.example.yaml、适配器文档和最新 README。给定资料列出了若干提供商和一个 langchain_openai:ChatOpenAI 示例，但没有提供完整模型兼容矩阵，因此不能仅凭环境变量名称断言所有模型均可用。

项目演进与版本边界

README 将当前内容标为 DeerFlow 2.0，并明确指出它是从头重写的版本。原始 Deep Research 框架仍维护在 main-1.x 分支，2.0 的活跃开发已经转移到当前主线。

因此，迁移或二次开发时应先确认目标分支和扩展接口。不要直接把 1.x 的代码、配置或插件当作 2.0 兼容组件；资料没有提供迁移指南或兼容性承诺，具体差异应以仓库对应分支文档为准。

部署决策与实施建议

对于个人或小团队验证，建议先在本机使用最小模型配置，不启用不必要的搜索、Bash、文件写入和消息通道。完成 make setup、make up、make doctor 后，再用不含敏感信息的测试任务验证模型、工具和沙箱链路。

对于组织内部部署，应把配置分成模型、外部工具、执行环境、消息入口和观测五类，并为每类配置单独的权限和轮换策略。若使用 PostgreSQL、多工作进程或拆分来源部署，需要进一步核验内部网关令牌、数据库连接、CORS、可信来源和反向代理之间的关系。

根据本文作者的经验判断，最值得优先验证的不是功能数量，而是任务失败后的可恢复性：包括工具超时、模型返回无效参数、沙箱执行失败、外部服务不可用、重复消息和敏感信息进入日志等情况。资料没有给出统一的恢复保证，因此这些测试应由部署团队自行建立。

项目地址与资源

以下链接均来自提供的仓库资料或 README 中列出的官方站点。外部模型、搜索、抓取和消息服务的使用条件，以对应站点当前公布的条款和文档为准。