AI Feeds
开源项目

deer-flow

deer-flow

字节跳动开源的多智能体编排框架，专注于超长周期任务自动化，集成记忆、沙箱、子智能体和外部工具。v2.0 完全重写，社区热度极高，支持 LangGraph、MCP 服务器以及 Telegram、飞书等 IM 渠道，适合需要自主规划、执行和迭代的复杂工作流。

README

🦌 DeerFlow - 2.0

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

Python Node.js License: MIT

bytedance%2Fdeer-flow | Trendshift

2026年2月28日，DeerFlow 在 2.0 版本发布后登顶 GitHub Trending 榜首 🏆。感谢我们不可思议的社区——是你们成就了这一切！💪🔥

DeerFlow（Deep Exploration and Efficient Research Flow，深度探索与高效研究流）是一个开源的超级 agent 框架（super agent harness），它编排子 agent（sub-agent）、记忆（memory）和沙箱（sandbox），通过可扩展技能（extensible skills） 几乎能够完成任何事情。

https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18

[!NOTE] DeerFlow 2.0 是彻底的重新构建。 它与 v1 代码不共享。如果你在寻找原始的 Deep Research 框架，它维护在 1.x 分支上——那里仍然欢迎贡献。积极开发已转移到 2.0。

官方网站

image

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

字节跳动火山引擎编程计划

英文方舟

InfoQuest

DeerFlow 新集成了 BytePlus 自主研发的智能搜索与爬取工具集——InfoQuest（支持免费在线体验）

InfoQuest_banner

目录

一行代码设置 agent

如果你使用 Claude Code、Codex、Cursor、Windsurf 或其他编码 agent，可以用一句话将设置说明交给它：

如有需要，先帮我克隆 DeerFlow，然后按照 https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md 的指引引导它为本地开发环境。

这段提示词是给编码 agent 的。它会告诉 agent 根据需要克隆仓库，在有 Docker 时优先选择 Docker，然后给出下一步的命令以及用户仍需提供的任何缺失配置就停止。

快速开始

配置

  1. 克隆 DeerFlow 仓库

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

  2. 运行设置向导

    从项目根目录（deer-flow/）执行：

    make setup

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

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

    随时运行 make doctor 来验证你的设置并获取可操作的修复提示。

    高级/手动配置：如果你更喜欢直接编辑 config.yaml，可以运行 make config 来复制完整的模板。完整的参考信息请参见 config.example.yaml，包括基于 CLI 的提供商（Codex CLI、Claude Code OAuth）、OpenRouter、Responses API 等。

    手动模型配置示例
    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）。

    若要路由 OpenAI 模型通过 /v1/responses，请继续使用 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 来切换推理，并在多轮 tool-call 对话中保留 vLLM 的非标准 reasoning 字段。为了向后兼容，旧的 thinking 配置会自动规范化。推理模型可能还需要服务器使用 --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 agent 条目与模型提供者是分开的——如果你配置了 acp_agents.codex，请将其指向一个 Codex ACP 适配器，例如 npx -y @zed-industries/codex-acp
    • 在 macOS 上，如果需要，显式导出 Claude Code 认证信息：
    eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"

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

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

运行应用

部署规模参考

使用下表作为选择运行 DeerFlow 方式时的实际起点：

部署目标 起始配置 推荐配置 备注
本地评估 / make dev 4 vCPU, 8 GB RAM, 20 GB 可用 SSD 8 vCPU, 16 GB RAM 适合一个开发者或一个使用托管模型 API 的轻量会话。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 推荐用于共享使用、多 agent 运行、报告生成或更重的沙箱工作负载。
  • 这些数值仅涵盖 DeerFlow 本身。如果你还托管本地 LLM，请单独为该服务分配资源。
  • Linux 加 Docker 是持久服务器的推荐部署目标。macOS 和 Windows 最好作为开发或评估环境对待。
  • 如果 CPU 或内存使用率持续占满，请首先减少并发运行，然后移至下一个更大的规模级别。
选项 1: Docker（推荐）

开发（热重载，源码挂载）：

make docker-init    # 拉取沙箱镜像（仅一次或镜像更新时）
make docker-start   # 启动服务（自动检测 config.yaml 中的沙箱模式）

make docker-start 仅在 config.yaml 使用 provisioner 模式（sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider 且包含 provisioner_url）时启动 provisioner。

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

后端进程会在下一次配置访问时自动检测 config.yaml 的更改，因此在开发期间模型元数据更新无需手动重启。

[!TIP] 在 Linux 上，如果基于 Docker 的命令失败并显示 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock，请将用户添加到 docker 组，重新登录后再试。完整修复方案参见 CONTRIBUTING.md。

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

make up     # 构建镜像并启动所有生产服务
make down   # 停止并移除容器

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

详细 Docker 开发指南请参见 CONTRIBUTING.md。

选项 2: 本地开发

如果你更喜欢在本地运行服务：

先决条件：先完成上述“配置”步骤（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 运行本地开发流程。基于 bash 的服务脚本不支持原生的 cmd.exe 和 PowerShell shell，WSL 也不保证支持，因为某些脚本依赖于 Git for Windows 的实用工具（如 cygpath）。

  1. 检查前提条件：

    make check  # 验证 Node.js 22+、pnpm、uv、nginx

  2. 安装依赖：

    make install  # 安装后端 + 前端依赖 + pre-commit 钩子

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

    # 如果使用 Docker/Container 沙箱，建议执行
make setup-sandbox

  4. （可选）加载示例记忆数据进行本地审查：

    python scripts/load_memory_sample.py

    这会将示例夹具复制到默认的本地运行时记忆文件中，以便审查者可以立即测试 Settings > Memory。 有关最短审查流程，请参见 backend/docs/MEMORY_SETTINGS_REVIEW.md。

  5. 启动服务：

    make dev

  6. 访问：http://localhost:2026

启动模式

DeerFlow 在 Gateway API 中运行 agent 运行时。开发模式启用热重载；生产模式使用预构建的前端。

本地前台 本地守护进程 Docker 开发 Docker 生产
开发 ./scripts/serve.sh --dev
make dev		 ./scripts/serve.sh --dev --daemon
make dev-daemon		 ./scripts/docker.sh start
make docker-start		 —
生产 ./scripts/serve.sh --prod
make start		 ./scripts/serve.sh --prod --daemon
make start-daemon		 — ./scripts/deploy.sh
make up
操作 本地 Docker 开发 Docker 生产
停止 ./scripts/serve.sh --stop
make stop		 ./scripts/docker.sh stop
make docker-stop		 ./scripts/deploy.sh down
make down
重启 ./scripts/serve.sh --restart [flags] ./scripts/docker.sh restart —

Gateway 拥有 /api/langgraph/* 路径，并在 nginx 之后将这些公开的 LangGraph 兼容路径转换为本地 /api/* 路由。

Docker 生产部署

deploy.sh 支持分别构建和启动：

# 一键完成（构建 + 启动）
deploy.sh

# 两步完成（先构建，稍后启动）
deploy.sh build              # 构建所有镜像
deploy.sh start              # 启动预构建的镜像

# 停止
deploy.sh down

高级配置

沙箱模式

DeerFlow 支持多种沙箱执行模式：

  • 本地执行（直接在主机上运行沙箱代码）
  • Docker 执行（在隔离的 Docker 容器中运行沙箱代码）
  • Docker 执行 + Kubernetes（通过 provisioner 服务在 Kubernetes Pod 中运行沙箱代码）

对于 Docker 开发，服务启动会遵循 config.yaml 中的沙箱模式。在本地/Docker 模式下，不会启动 provisioner。

参见 沙箱配置指南 配置你偏好的模式。

MCP 服务器

DeerFlow 支持可配置的 MCP 服务器和技能来扩展其能力。对于 HTTP/SSE MCP 服务器，支持 OAuth 令牌流程（client_credentials、refresh_token）。 详细说明请参见 MCP 服务器指南。

IM 渠道

DeerFlow 支持从即时通讯应用接收任务。渠道在配置后会自动启动——所有渠道都不需要公网 IP。

渠道 传输方式 难度
Telegram Bot API（长轮询） 简单
Slack Socket 模式 中等
Feishu / Lark WebSocket 中等
微信 腾讯 iLink（长轮询） 中等
企业微信 WebSocket 中等
钉钉 Stream Push（WebSocket） 中等

在 config.yaml 中的配置：

channels:
  # LangGraph 兼容的 Gateway API 基础 URL（默认：http://localhost:8001/api）
  langgraph_url: http://localhost:8001/api
  # Gateway API URL（默认：http://localhost:8001）
  gateway_url: http://localhost:8001

  # 可选：所有移动渠道的全局会话默认值
  session:
    assistant_id: lead_agent  # 或自定义 agent 名称；自定义 agent 通过 lead_agent + agent_name 路由
    config:
      recursion_limit: 100
    context:
      thinking_enabled: true
      is_plan_mode: false
      subagent_enabled: false

  feishu:
    enabled: true
    app_id: $FEISHU_APP_ID
    app_secret: $FEISHU_APP_SECRET
    # domain: https://open.feishu.cn       # 中国（默认）
    # domain: https://open.larksuite.com   # 国际

  wecom:
    enabled: true
    bot_id: $WECOM_BOT_ID
    bot_secret: $WECOM_BOT_SECRET

  slack:
    enabled: true
    bot_token: $SLACK_BOT_TOKEN     # xoxb-...
    app_token: $SLACK_APP_TOKEN     # xapp-... (Socket 模式)
    allowed_users: []               # 空 = 允许所有用户

  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []               # 空 = 允许所有用户

  wechat:
    enabled: false
    bot_token: $WECHAT_BOT_TOKEN
    ilink_bot_id: $WECHAT_ILINK_BOT_ID
    qrcode_login_enabled: true      # 可选：当 bot_token 缺失时允许首次扫码引导
    allowed_users: []               # 空 = 允许所有用户
    polling_timeout: 35
    state_dir: ./.deer-flow/wechat/state
    max_inbound_image_bytes: 20971520
    max_outbound_image_bytes: 20971520
    max_inbound_file_bytes: 52428800
    max_outbound_file_bytes: 52428800

    # 可选：按渠道/用户的会话设置
    session:
      assistant_id: mobile-agent  # 此处也支持自定义 agent 名称
      context:
        thinking_enabled: false
      users:
        "123456789":
          assistant_id: vip-agent
          config:
            recursion_limit: 150
          context:
            thinking_enabled: true
            subagent_enabled: true

  dingtalk:
    enabled: true
    client_id: $DINGTALK_CLIENT_ID             # 钉钉应用的 Client ID
    client_secret: $DINGTALK_CLIENT_SECRET     # 钉钉应用的 Client Secret
    allowed_users: []                          # 空 = 允许所有用户
    card_template_id: ""                       # 可选：流式打字机效果的 AI 卡片模板 ID

注意事项：

  • assistant_id: lead_agent 直接调用默认的 LangGraph 助手。
  • 如果 assistant_id 设置为自定义 agent 名称，DeerFlow 仍然通过 lead_agent 路由，并注入该值作为 agent_name，因此自定义 agent 的 SOUL/config 对 IM 渠道生效。
  • IM 渠道工作进程内部调用 Gateway 的 LangGraph 兼容 API，并自动附加进程本地的内部认证以及创建线程和运行所需的 CSRF cookie/header 对。

在 .env 文件中设置相应的 API 密钥：

# Telegram
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

# Feishu / Lark
FEISHU_APP_ID=cli_xxxx
FEISHU_APP_SECRET=your_app_secret

# 微信 iLink
WECHAT_BOT_TOKEN=your_ilink_bot_token
WECHAT_ILINK_BOT_ID=your_ilink_bot_id

# 企业微信
WECOM_BOT_ID=your_bot_id
WECOM_BOT_SECRET=your_bot_secret

# 钉钉
DINGTALK_CLIENT_ID=your_client_id
DINGTALK_CLIENT_SECRET=your_client_secret

Telegram 设置

  1. 与 @BotFather 对话，发送 /newbot，然后复制 HTTP API 令牌。
  2. 在 .env 中设置 TELEGRAM_BOT_TOKEN，并在 config.yaml 中启用该渠道。

Slack 设置

  1. 在 api.slack.com/apps 创建一个 Slack App → Create New App → From scratch。
  2. 在 OAuth & Permissions 下，添加 Bot Token Scopes：app_mentions:read、chat:write、im:history、im:read、im:write、files:write。
  3. 启用 Socket Mode → 生成一个应用级令牌（xapp-…），作用域为 connections:write。
  4. 在 Event Subscriptions 下，订阅机器人事件：app_mention、message.im。
  5. 在 .env 中设置 SLACK_BOT_TOKEN 和 SLACK_APP_TOKEN，并在 config.yaml 中启用该渠道。

飞书 / Lark 设置

  1. 在 飞书开放平台 创建一个应用 → 启用 Bot 能力。
  2. 添加权限：im:message、im:message.p2p_msg:readonly、im:resource。
  3. 在 Events 下，订阅 im.message.receive_v1，并选择 Long Connection 模式。
  4. 复制 App ID 和 App Secret。在 .env 中设置 FEISHU_APP_ID 和 FEISHU_APP_SECRET，并在 config.yaml 中启用该渠道。

微信设置

  1. 在 config.yaml 中启用 wechat 渠道。
  2. 在 .env 中设置 WECHAT_BOT_TOKEN，或设置 qrcode_login_enabled: true 以进行首次扫码引导。
  3. 当 bot_token 缺失且启用了扫码引导时，查看后端日志，找到 iLink 返回的二维码内容，并完成绑定流程。
  4. 扫码流程成功后，DeerFlow 将获取的令牌持久化到 state_dir 下，供后续重启使用。
  5. 对于 Docker Compose 部署，请将 state_dir 保留在持久卷上，以便 get_updates_buf 游标和已保存的认证状态在重启后仍然存在。

企业微信设置

  1. 在企业微信 AI 机器人平台创建一个机器人，获取 bot_id 和 bot_secret。
  2. 在 config.yaml 中启用 channels.wecom，并填写 bot_id / bot_secret。
  3. 在 .env 中设置 WECOM_BOT_ID 和 WECOM_BOT_SECRET。
  4. 确保后端依赖包含 wecom-aibot-python-sdk。该渠道使用 WebSocket 长连接，不需要公网回调 URL。
  5. 当前集成支持接收文本、图片和文件消息。agent 生成的最终图片/文件也会回传到企业微信对话中。

钉钉设置

  1. 在钉钉开发者平台创建一个钉钉应用，并启用 Robot 能力。
  2. 在机器人配置页面将消息接收模式设置为 Stream 模式。
  3. 复制 Client ID 和 Client Secret，在 .env 中设置 DINGTALK_CLIENT_ID 和 DINGTALK_CLIENT_SECRET，并在 config.yaml 中启用该渠道。
  4. (可选) 要启用流式 AI 卡片回复（打字机效果），在钉钉卡片平台创建一个 AI 卡片 模板，然后在 config.yaml 中设置 card_template_id 为模板 ID。你还需要申请 Card.Streaming.Write 和 Card.Instance.Write 权限。

当 DeerFlow 在 Docker Compose 中运行时，IM 渠道在 gateway 容器内执行。在这种情况下，不要将 channels.langgraph_url 或 channels.gateway_url 指向 localhost；应使用容器服务名称，例如 http://gateway:8001/api 和 http://gateway:8001，或设置 DEER_FLOW_CHANNELS_LANGGRAPH_URL 和 DEER_FLOW_CHANNELS_GATEWAY_URL。

命令

一旦渠道连接上，你可以直接从聊天中与 DeerFlow 交互：

命令 描述
/new 开始新的对话
/status 显示当前线程信息
/models 列出可用的模型
/memory 查看记忆
/help 显示帮助

没有命令前缀的消息被视为普通聊天——DeerFlow 会创建一个线程并以对话方式回复。

LangSmith 追踪

DeerFlow 内置了 LangSmith 的可观测性集成。启用后，所有 LLM 调用、agent 运行和工具执行都会被追踪，并在 LangSmith 仪表板中可见。

在 .env 文件中添加以下内容：

LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
LANGSMITH_PROJECT=xxx
Langfuse 追踪

DeerFlow 也支持 Langfuse 对 LangChain 兼容运行的可观测性。

在 .env 文件中添加以下内容：

LANGFUSE_TRACING=true
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_BASE_URL=https://cloud.langfuse.com

如果你使用自托管的 Langfuse 实例，请将 LANGFUSE_BASE_URL 设置为你的部署 URL。

同时使用两个追踪提供商

如果同时启用了 LangSmith 和 Langfuse，DeerFlow 会附加两个追踪回调，并将相同的模型活动报告给两个系统。

如果某个提供商被明确启用但缺少必要的凭证，或者其回调初始化失败，DeerFlow 会在模型创建期间初始化追踪时快速失败，错误消息会指出导致失败的提供商。

对于 Docker 部署，追踪默认是禁用的。请在 .env 中设置 LANGSMITH_TRACING=true 和 LANGSMITH_API_KEY 以启用。

从 Deep Research 到超级 agent 框架

DeerFlow 最初是一个 Deep Research 框架——社区迅速跟进。自发布以来，开发者将其应用范围远远超出了研究：构建数据管道、生成幻灯片、搭建仪表板、自动化内容工作流。这些我们始料未及。

这告诉了我们一个重要的事实：DeerFlow 不仅仅是一个研究工具。它是一个框架（harness）——一个为 agent 提供实际完成工作所需基础设施的运行时。

因此，我们从头重建了它。

DeerFlow 2.0 不再是一个需要你拼凑的框架。它是一个超级 agent 框架——开箱即用，完全可扩展。基于 LangGraph 和 LangChain 构建，它出厂即配备 agent 所需的一切：文件系统、记忆、技能、沙箱感知的执行环境，以及为复杂多步骤任务规划并生成子 agent 的能力。

可以直接使用。也可以拆解后按需定制。

核心特性

技能与工具

技能是让 DeerFlow 能够几乎完成任何事情的关键。

标准 Agent 技能是一个结构化的能力模块——一个 Markdown 文件，定义了工作流、最佳实践以及对支持资源的引用。DeerFlow 出厂即配备用于研究、报告生成、幻灯片创建、网页、图像和视频生成等的内置技能。但真正的威力在于可扩展性：添加你自己的技能，替换内置技能，或将它们组合成复合工作流。

技能是渐进式加载的——只在任务需要时才加载，而不是一次性全部加载。这保持了上下文窗口的精简，使 DeerFlow 即使在使用对令牌敏感的模型时也能良好运行。

当你通过 Gateway 安装 .skill 存档时，DeerFlow 接受标准的可选 frontmatter 元数据，如 version、author

开源项目bytedance2026-05-06原文

相关内容