字节DeerFlow：开源SuperAgent编程框架

English | 中文 | 日本語 | Français | Русский

2026 年 2 月 28 日，DeerFlow 在第 2 版发布后登上 GitHub Trending 🏆 榜首。万分感谢我们出色的社区——是你们成就了这一切！💪🔥

DeerFlow（Deep Exploration and Efficient Research Flow，深度探索与高效研究流）是一个开源的超级智能体框架，通过协调子智能体、记忆和沙箱，几乎可以完成任何任务，并由可扩展的技能驱动。

DeerFlow 2.0 是一次从零开始的重写，与 v1 没有共享任何代码。如果你正在寻找原始的 Deep Research 框架，它仍在 1.x 分支上维护，也依然欢迎为该分支贡献代码。当前的活跃开发已转移到 2.0。

访问我们的官方网站，了解更多信息并观看真实演示。

LLM Space——来认识一下 DeerFlow 背后的秘密武器：一款桌面工具，可用于制作智能体创意原型、检查框架的每个步骤、重现故障并对性能进行基准测试。

字节跳动火山引擎 Coding Plan

我们强烈推荐使用 Doubao-Seed-2.0-Code、DeepSeek v3.2 和 Kimi 2.5 运行 DeerFlow。

DeerFlow 新近集成了由 BytePlus 独立开发的智能搜索与抓取工具集——InfoQuest（支持免费在线体验）。

🦌 DeerFlow - 2.0 官方网站 字节跳动火山引擎 Coding Plan InfoQuest 目录 一句话设置智能体 快速开始 配置 运行应用 部署规模 选项 1：Docker（推荐） 选项 2：本地开发 高级功能 沙箱模式 MCP Server 即时通信渠道 LangSmith 链路追踪 Langfuse 链路追踪 Monocle 链路追踪 使用多个提供商 从 Deep Research 到超级智能体框架 核心功能 技能与工具 Claude Code 集成 会话目标 手动上下文压缩 子智能体 沙箱与文件系统 上下文工程 长期记忆 推荐模型 嵌入式 Python 客户端 定时任务 终端工作台（TUI） 文档 ⚠️ 安全提示 部署不当可能带来安全风险 安全建议 贡献 许可证 致谢 核心贡献者 Star 历史

字节跳动火山引擎 Coding Plan

快速开始 配置 运行应用 部署规模 选项 1：Docker（推荐） 选项 2：本地开发 高级功能 沙箱模式 MCP Server 即时通信渠道 LangSmith 链路追踪 Langfuse 链路追踪 Monocle 链路追踪 使用多个提供商

运行应用 部署规模 选项 1：Docker（推荐） 选项 2：本地开发

选项 1：Docker（推荐）

选项 2：本地开发

高级功能 沙箱模式 MCP Server 即时通信渠道 LangSmith 链路追踪 Langfuse 链路追踪 Monocle 链路追踪 使用多个提供商

使用多个提供商

从 Deep Research 到超级智能体框架

核心功能 技能与工具 Claude Code 集成 会话目标 手动上下文压缩 子智能体 沙箱与文件系统 上下文工程 长期记忆

技能与工具 Claude Code 集成

Claude Code 集成

手动上下文压缩

沙箱与文件系统

嵌入式 Python 客户端

终端工作台（TUI）

⚠️ 安全提示 部署不当可能带来安全风险 安全建议

部署不当可能带来安全风险

安全建议

致谢 核心贡献者

如果你使用 Claude Code、Codex、Cursor、Windsurf 或其他编程智能体，只需用一句话将设置说明交给它：

Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md

该提示词专为编程智能体设计。它会指示智能体在需要时克隆仓库、在 Docker 可用时选择 Docker，并在结束时给出准确的下一条命令，以及仍需用户提供的所有缺失配置。

克隆 DeerFlow 仓库 git clone https://github.com/bytedance/deer-flow.git cd deer-flow

克隆 DeerFlow 仓库

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

运行设置向导

从项目根目录 (deer-flow/) 运行：

make setup

这将启动一个交互式向导，引导你选择 LLM 提供商、可选的网络搜索，以及执行/安全偏好，如沙盒模式、bash 访问和文件写入工具。它生成一个最小的 config.yaml 并将你的密钥写入 .env。耗时约 2 分钟。

向导还允许你配置可选的网络搜索提供商，或暂时跳过。

可以随时运行 make doctor 来验证你的设置并获取可操作的修复提示。如果你要在 GitHub 上提交关于本地设置或运行时问题的 issue，运行 make support-bundle。该命令会打印后续步骤，写入一个 *-issue-summary.md 文件以粘贴到 issue 中，一个 *-issue-draft.md 文件用于 AI 辅助的 issue 提交，以及 .deer-flow/support-bundles/ 下的一个可选证据 zip。如果 AI 智能体提交该 issue，从草稿开始，替换每个 REQUIRED 占位符而不是编造缺失的事实。只有在维护者要求时或仅摘要不足时才附加 zip。维护者和 AI 分诊工具可以从 triage.json 开始；该 bundle 仅包含经过处理的诊断和文件清单，不包括 .env、原始对话消息或用户文件内容。

高级 / 手动配置：如果你更喜欢直接编辑 config.yaml，运行 make config 改为复制完整模板。参见 config.example.yaml 了解完整参考，包括 CLI 支持的提供商（Codex CLI、Claude Code OAuth）、OpenRouter、Responses API、子智能体运行时上限（如 subagents.max_total_per_run）等。

可选的每个模型定价必须在所有定价模型中使用一种货币。当货币混合时，DeerFlow 会禁用控制台成本估计，而不是呈现无效的总和。

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

  - name: gpt-5-responses
    display_name: GPT-5 (Responses API)
    use: langchain_openai:ChatOpenAI
    model: gpt-5
    api_key: $OPENAI_API_KEY
    use_responses_api: true
    output_version: responses/v1

  - 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
    when_thinking_enabled:
      extra_body:
        chat_template_kwargs:
          enable_thinking: true

OpenRouter 和类似的 OpenAI 兼容网关应该配置 langchain_openai:ChatOpenAI 加上 base_url。如果你更喜欢特定于提供商的环境变量名称，将 api_key 明确指向该变量（例如 api_key: $OPENROUTER_API_KEY）。

要通过 /v1/responses 路由 OpenAI 模型，继续使用 langchain_openai:ChatOpenAI 并设置 use_responses_api: true 和 output_version: responses/v1。

对于 vLLM 0.19.0，使用 deerflow.models.vllm_provider:VllmChatModel。对于 Qwen 风格的推理模型，DeerFlow 使用 extra_body.chat_template_kwargs.enable_thinking 切换推理，并在多轮工具调用对话中保留 vLLM 的非标准推理字段。旧版思维配置会自动规范化以保持向后兼容性。如果端点在每个流式块上报告累积使用快照，设置 cumulative_stream_usage: true 使 DeerFlow 将这些快照转换为每块增量；默认禁用该选项，当没有稳定的 completion id 时保持使用量不变。推理模型可能还需要使用 --reasoning-parser ... 启动服务器。如果你的本地 vLLM 部署接受任何非空 API 密钥，你仍然可以将 VLLM_API_KEY 设置为占位符值。

CLI 支持的提供商示例：

models:
  - name: gpt-5.4
    display_name: GPT-5.4 (Codex CLI)
    use: deerflow.models.openai_codex_provider:CodexChatModel
    model: gpt-5.4
    supports_thinking: true
    supports_reasoning_effort: true

- name: claude-sonnet-4.6
    display_name: Claude Sonnet 4.6 (Claude Code OAuth)
    use: deerflow.models.claude_provider:ClaudeChatModel
    model: claude-sonnet-4-6
    max_tokens: 4096
    supports_thinking: true

Codex CLI 读取 ~/.codex/auth.json

Claude Code 接受 CLAUDE_CODE_OAUTH_TOKEN、ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_CREDENTIALS_PATH 或 ~/.claude/.credentials.json

ACP 智能体条目与模型提供商相互独立——如果你配置了 acp_agents.codex，请将其指向 Codex ACP 适配器，例如 npx -y @zed-industries/codex-acp

在 macOS 上，如有需要，请显式导出 Claude Code 身份验证信息：

eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"

API 密钥也可以在 .env 中手动设置（推荐），或在 shell 中导出：

OPENAI_API_KEY=your-openai-api-key
TAVILY_API_KEY=your-tavily-api-key

运行应用程序

选择 DeerFlow 的运行方式时，可以将下表作为实用的起点：

这些数字仅涵盖 DeerFlow 本身。如果你还托管了本地 LLM，请单独评估该服务所需的资源规格。

对于持久运行的服务器，推荐使用 Linux 加 Docker 作为部署目标。macOS 和 Windows 更适合作为开发或评估环境。

如果 CPU 或内存使用率持续处于满载状态，请先减少并发运行数量，然后再升级到下一个资源规格档位。

开发环境（热重载、源码挂载）：

make docker-init    # Pull sandbox image (only once or when image updates)
make docker-start   # Start services (auto-detects sandbox mode from config.yaml)

仅当 config.yaml 使用 provisioner 模式（sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider 并配置了 provisioner_url）时，make docker-start 才会启动 provisioner。

Docker 构建默认使用上游 uv registry。如果需要在受限网络中使用速度更快的镜像源，请在运行 make docker-init 或 make docker-start 前导出 UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple 和 NPM_REGISTRY=https://registry.npmmirror.com。

本地 AIO 沙箱的控制流量始终直连：环回地址、私有地址、单标签集群主机以及 Docker/Podman 内部主机名不会继承 HTTP_PROXY 或 HTTPS_PROXY。外部沙箱 FQDN 和公网 IP 仍会遵循环境中的代理设置。

后端进程会在下一次访问配置时自动获取 config.yaml 的更改，因此在开发期间更新模型元数据无需手动重启。检查点存储设置 database.checkpoint_channel_mode 和 database.checkpoint_delta.snapshot_frequency（默认值为 10）是例外：进程首次构建智能体时（包括通过 DeerFlowClient 构建）会固定这两个设置，要安全地更改它们，必须重启进程。

在 Linux 上，如果基于 Docker 的命令在尝试连接 unix:///var/run/docker.sock 上的 Docker daemon socket 时因 permission denied 而失败，请将你的用户添加到 docker 用户组，重新登录后再重试。完整的修复方法请参阅 CONTRIBUTING.md。

生产环境（在本地构建镜像，挂载运行时配置和数据）：

make up     # Build images and start all production services
make down   # Stop and remove containers

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

对于持久化部署，请将 database.backend 配置为 sqlite 或 postgres。选定的后端由 LangGraph checkpointer、LangGraph Store 和 DeerFlow 应用程序数据共享。为保持向后兼容，如果存在已弃用的 checkpointer 配置节，它会覆盖前两者的配置。

统一的 nginx 端点默认采用同源模式，不会发送浏览器 CORS 响应头。如果你运行的是跨源或经过端口转发的浏览器客户端，请将 GATEWAY_CORS_ORIGINS 设置为以逗号分隔的精确源地址，例如 http://localhost:3000；Gateway 随后会应用 CORS 允许列表及与之匹配的 CSRF 源检查。

浏览器登录使用 HttpOnly 会话 Cookie。登录页面提供“保持登录状态”选项；当请求使用 HTTPS（包括受信任的 X-Forwarded-Proto: https）或 localhost HTTP 时，该选项会延长浏览器会话。localhost 例外规则使用直接请求中的 Host，并忽略转发的 host 请求头。公共 HTTP 部署（包括许多临时沙箱 URL）默认会回退到会话 Cookie。DeerFlow 绝不会在浏览器存储中保存密码；UI 最多只会记住电子邮件地址。

DeerFlow 仍使用 Forwarded / X-Forwarded-* 请求头，在代理后方还原浏览器侧的协议和源。随附的 nginx 会设置 X-Forwarded-Proto，但会保留上游的 HTTPS 值，并且不会覆盖所有转发请求头。请配置外层可信代理，在流量到达 DeerFlow 之前替换或移除客户端提供的转发请求头。

Gateway 仍在进程内管理活跃的运行任务，因此生产环境默认只使用一个 Gateway worker（GATEWAY_WORKERS=1）。多 worker 部署需要使用 Postgres、Redis 流桥接器（stream_bridge.type: redis）、run_ownership.heartbeat_enabled: true 以及 run_events.backend: db；进程本地的内存/JSONL 事件存储无法在多个 worker 之间强制保证交付回执的单例性。该桥接器在各 worker 之间共享 SSE 交付，以及有界的 Last-Event-ID 重放。当有效的重连游标已被裁剪，或者已经建立空流等待的订阅者在首次收到数据前落后时，Memory 和 Redis 会发送机器可读的 SSE gap 事件，而不是悄无声息地返回不完整的重放；Web UI 会重新加载持久化的线程/事件状态，并从保留数据的尾部继续。租约协调会将来自失效 worker 的运行标记为错误，持久化其交付回执，发布终止流标记，安排保留流的清理，并更新受影响线程的状态。如果终止状态发布失败，SSE 和 /wait 消费者还会在收到心跳时刷新持久化状态，作为兜底机制。格式错误的 Redis 重连 ID 会直接追踪新的实时事件，而不会重放保留的缓冲区；滚动更新的保留缓冲区 TTL（stream_ttl_seconds）仍然只是清理安全网，而不是运行超时时间。IM 渠道状态和其他进程本地服务仍需各自实现多 worker 协调。

运行取消请求可能会到达任意 Gateway worker。非所有者 worker 现在会为当前所有者持久化中断或回滚请求，所有者会在租约续期期间观察到该请求，并执行正常的取消流程；仅由负载均衡器路由不再会导致 409。即使重试请求到达所有者，第一个被接受的操作仍会生效，并且已接受的取消操作会与所有者的完成操作进行原子竞争。失效的所有者仍会遵循租约接管和孤儿恢复流程。因此，取消延迟的上限由租约心跳间隔决定。

启用租约心跳后，瞬时 RunStore 续期错误只会重试到最后一次确认的租约到期为止；随后，过期的 worker 会取消本地执行，并禁止进行检查点保存、完成钩子调用、交付回执持久化及线程状态最终确认。已经在执行中的远程工具副作用仍可能不受本地取消控制。

协调流程使用原子接管声明，并在选出候选对象后重新检查租约，因此成功的所有者续期会优先于孤儿恢复，而且只能有一个协调器报告某次运行已恢复。当多个 Gateway worker 共享 Docker/AIO 或 E2B 沙箱后端时，还需配置 sandbox.ownership.type: redis；E2B 会在后台启动和定期协调期间使用这些租约，从而避免重复清理或孤儿清理误终止其他 worker 的活跃沙箱。

有关详细的 Docker 开发指南，请参阅 CONTRIBUTING.md。

如果你倾向于在本地运行服务：

前置条件：请先完成上文“配置”部分的步骤（make setup）。make dev 要求项目根目录中存在有效的 config.yaml。设置 DEER_FLOW_PROJECT_ROOT 可以显式指定该根目录，设置 DEER_FLOW_CONFIG_PATH 可以指向特定的配置文件。运行时状态默认存储在项目根目录下的 .deer-flow 中，可以通过 DEER_FLOW_HOME 更改其位置；技能默认存储在项目根目录下的 skills/ 中，可以通过 DEER_FLOW_SKILLS_PATH 更改其位置。启动前请运行 make doctor 验证配置。在 Windows 上，请从 Git Bash 运行本地开发流程。不支持原生的 cmd.exe 和 PowerShell shell，因为服务脚本基于 bash；也不保证支持 WSL，因为部分脚本依赖 Git for Windows 提供的工具，例如 cygpath。

检查前置依赖：make check # Verifies Node.js 22+, pnpm, uv, nginx。本地的 make check、make install、make dev 和 make start 入口在可用时会直接使用 pnpm/pnpm.cmd 可执行文件，否则回退到 corepack pnpm。Corepack 从 frontend/ 目录运行，因此会遵循 frontend/package.json 中通过 packageManager 固定的版本；无需启用全局 pnpm shim。

make check  # Verifies Node.js 22+, pnpm, uv, nginx

当系统中存在可直接调用的 pnpm/pnpm.cmd 可执行文件时，本地的 make check、make install、make dev 和 make start 入口会直接使用它；否则会回退到 corepack pnpm。Corepack 从 frontend/ 目录运行，因此会遵循 frontend/package.json 中通过 packageManager 锁定的版本；无需启用全局 pnpm shim。

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

安装依赖：

make install  # Install backend + frontend dependencies + pre-commit hooks

（可选）预拉取沙箱镜像：# Recommended if using Docker/Container-based sandbox make setup-sandbox

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

# Recommended if using Docker/Container-based sandbox
make setup-sandbox

（可选）加载示例记忆数据以供本地审查：python scripts/load_memory_sample.py。这会将示例 fixture 复制到默认的本地运行时记忆文件中，以便审查人员能够立即测试 Settings > Memory。最简审查流程请参阅 backend/docs/MEMORY_SETTINGS_REVIEW.md。

（可选）加载示例记忆数据以供本地审查：

python scripts/load_memory_sample.py

这会将示例 fixture 复制到默认的本地运行时记忆文件中，以便审查人员能够立即测试 Settings > Memory。最简审查流程请参阅 backend/docs/MEMORY_SETTINGS_REVIEW.md。

启动服务：make dev

make dev

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

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

DeerFlow 运行智能体运行时