bytedance/deer-flow 源码：https://github.com/bytedance/deer-flow

🦌 DeerFlow - 2.0

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

Python Node.js 许可证：MIT

2026年2月28日，DeerFlow凭借2.0版本登上了GitHub Trending的🏆第一名。衷心感谢我们了不起的社区——是你们让这一切成为现实！💪🔥

DeerFlow（Deep Exploration and Efficient Research Flow，深度探索与高效研究流）是一个开源超级Agent框架，它编排子Agent、记忆和沙箱，依托可扩展技能几乎可以完成任何任务。

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

DeerFlow 2.0 是完全重写的版本。 它与v1没有共享代码。如果您在寻找原始的Deep Research框架，它维护在 1.x 分支上（https://github.com/bytedance/deer-flow/tree/main-1.x）——那里仍然欢迎贡献。活跃开发已迁移至2.0。

官方网站

在我们的官方网站（https://deerflow.tech）了解更多并查看真实演示。

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

• 我们强烈建议使用豆包Seed-2.0-Code、DeepSeek v3.2和Kimi 2.5来运行DeerFlow
• 了解更多（https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow）
• 中国大陆地区的开发者请点击这里（https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow）

InfoQuest

DeerFlow新集成了字节跳动旗下的智能搜索与抓取工具集——InfoQuest（支持免费在线体验）（https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest）

目录

• 🦌 DeerFlow - 2.0
• 官方网站
• 字节跳动火山引擎编程计划
• InfoQuest
• 目录
• 一行命令设置Agent
• 快速开始
  • 配置
  • 运行应用
    • 部署规模参考
    • 选项1：Docker（推荐）
    • 选项2：本地开发
  • 高级
    • 沙箱模式
    • MCP服务器
    • IM渠道
    • LangSmith追踪
    • Langfuse追踪
    • 同时使用两者
• 从Deep Research到超级Agent框架
• 核心特性
  • 技能与工具
  • Claude Code集成
  • 子Agent
  • 沙箱与文件系统
  • 上下文工程
  • 长期记忆
  • 推荐模型
  • 嵌入式Python客户端
  • 文档
• ⚠️ 安全注意事项
  • 不当部署可能引入安全风险
  • 安全建议
• 参与贡献
• 许可证
• 致谢
  • 主要贡献者
  • Star历史

一行命令设置Agent

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

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

该提示面向代码Agent。它告诉Agent：如果需要则克隆仓库，在可用时选择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）。

要通过 /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的非标准 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)"
  

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或内存使用率一直居高不下，请先减少并发运行数量，然后迁移到下一个规模层。

选项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 的更改，因此在开发期间更新模型元数据不需要手动重启。

在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

统一的nginx端点默认是同源的，不会发出浏览器CORS头部。如果您运行的是分离源或端口转发的浏览器客户端，请将 GATEWAY_CORS_ORIGINS 设置为逗号分隔的精确源，例如 http://localhost:3000；然后Gateway将应用CORS白名单和匹配的CSRF源检查。

Gateway将运行状态（RunManager和流桥）保存在进程中，因此生产环境默认使用单个Gateway工作进程（GATEWAY_WORKERS=1）。在没有共享跨工作进程流桥（目前尚不可用）的情况下增加工作进程数量，会破坏运行取消、SSE重连、请求去重和IM渠道，因为nginx不使用粘性会话，且每个工作进程维护自己的运行状态。请通过增加CPU/RAM来扩展单个工作进程（或将数据库和沙箱移至专用层），而不是增加 GATEWAY_WORKERS。

请参阅 CONTRIBUTING.md 获取详细的Docker开发指南。

选项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运行本地开发流程。原生的 cmd.exe 和PowerShell shell不支持基于bash的服务脚本，也不保证WSL兼容，因为某些脚本依赖于Git for Windows的实用程序，如 cygpath。

1. 检查先决条件：

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

2. 安装依赖：

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

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

# 如果使用Docker/基于容器的沙箱，建议执行此操作
make setup-sandbox

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

python scripts/load_memory_sample.py

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

5. 启动服务：

make dev

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

启动模式

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

Gateway拥有 /api/langgraph/* 路由，并将这些公共的LangGraph兼容路径转换为nginx后原生的 /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 token流程（client_credentials、refresh_token）。请参阅MCP服务器指南获取详细说明。

IM渠道

DeerFlow支持从即时通讯应用接收任务。渠道在配置后自动启动——其中任何一个都不需要公网IP。DeerFlow还可以在工作区UI中公开用户拥有的IM渠道连接。当启用 channel_connections 时，登录用户可以从侧边栏/设置 > 渠道绑定Telegram、Slack、Discord、飞书/Lark、钉钉、微信或企业微信。它复用现有的出站 channels.* 传输，因此不需要公网IP或提供商回调URL。传入的IM消息随后在关联的DeerFlow用户账户下运行。请参阅[IM渠道连接](backend/docs/IM_CHANNEL_CONNECTIONS.m