🦌 DeerFlow - 2.0

英语 | 中文 | 日语 | 法语 | 俄语

2026年2月28日，DeerFlow在推出2.0版本后，荣登GitHub趋势榜榜首！衷心感谢我们了不起的社区——是你们让这一切成为现实！💪🔥

DeerFlow（Deep Exploration and Efficient Research Flow）是一个开源的超级智能体框架，用于编排子智能体、记忆模块和沙盒环境，以完成几乎任何任务——这一切都由可扩展的能力模块驱动。

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

[!NOTE] DeerFlow 2.0 是一次从零开始的重写。 它与 v1 版本没有任何代码共享。如果您正在寻找最初的 Deep Research 框架，它仍然维护在 1.x 分支上——欢迎继续贡献代码。目前的开发重心已转移到 2.0 版本。

官方网站

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

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

• 我们强烈建议使用 Doubao-Seed-2.0-Code、DeepSeek v3.2 和 Kimi 2.5 来运行 DeerFlow
• 了解更多
• 中国大陆地区的开发者请点击这里

InfoQuest

DeerFlow 新近集成了字节跳动自主研发的智能搜索与爬虫工具套件——InfoQuest（支持免费在线体验）

---

目录

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

一行式智能体设置

如果您使用 Claude Code、Codex、Cursor、Windsurf 或其他编程智能体，只需用一句话就能向其传达设置指令：

如果需要的话帮我克隆 DeerFlow，然后按照 https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md 的说明进行本地开发的初始化。

这条提示专为编程智能体设计。它会指示智能体在必要时克隆仓库，在有 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）。

   若要通过 /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 代理条目与模型提供商是分开的——如果您配置了 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 的运行方式时，可参考下表作为实际的起点：

部署目标	起始配置	推荐配置	备注
本地评估 / make dev	4 vCPU、8 GB 内存、20 GB 空闲 SSD	8 vCPU、16 GB 内存	适合单个开发者或使用托管模型 API 的轻量级会话。2 vCPU / 4 GB 通常不够。
Docker 开发 / make docker-start	4 vCPU、8 GB 内存、25 GB 空闲 SSD	8 vCPU、16 GB 内存	镜像构建、绑定挂载和沙盒容器比纯本地开发需要更多的资源余量。
长期运行服务器 / make up	8 vCPU、16 GB 内存、40 GB 空闲 SSD	16 vCPU、32 GB 内存	更适合共享使用、多智能体运行、报告生成或较重的沙盒工作负载。

• 上述配置仅针对 DeerFlow 本身。如果您还部署了本地 LLM，则需单独为其规划资源。
• 建议在 Linux 系统上使用 Docker 部署持久化服务器。macOS 和 Windows 则更适合用作开发或评估环境。
• 如果 CPU 或内存占用持续居高不下，请先减少并发运行数量，再考虑升级到更高一级的资源配置。

方案一：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   # 停止并移除容器

[!NOTE] 当前 LangGraph 智能体服务器通过 langgraph dev（开源 CLI 服务器）运行。

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

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

方案二：本地开发

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

前提条件：请先完成上述“配置”步骤（make setup）。make dev 需要在项目根目录下存在有效的 config.yaml 文件（可通过 DEER_FLOW_CONFIG_PATH 覆盖）。在启动前，请运行 make doctor 检查您的环境配置是否正确。 在 Windows 系统上，请使用 Git Bash 来运行本地开发流程。原生的 cmd.exe 和 PowerShell 不支持基于 bash 的服务脚本，而 WSL 也未必适用，因为部分脚本依赖于 Windows 版 Git 提供的工具，如 cygpath。

1. 检查前置条件：

   make check  # 验证 Node.js 22+、pnpm、uv、nginx 是否已安装
   

2. 安装依赖：

   make install  # 安装前后端依赖
   

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 支持两种维度的多种启动模式：

• 开发 / 生产 — 开发模式支持热重载；生产模式则使用预构建的前端。
• 标准 / 网关 — 标准模式使用独立的 LangGraph 服务器（共 4 个进程）；网关模式（实验性）则将智能体运行时嵌入到网关 API 中（共 3 个进程）。

	本地前台模式	本地守护进程模式	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 --dev --gateway make dev-pro	./scripts/serve.sh --dev --gateway --daemon make dev-daemon-pro	./scripts/docker.sh start --gateway make docker-start-pro	—
生产模式	./scripts/serve.sh --prod make start	./scripts/serve.sh --prod --daemon make start-daemon	—	./scripts/deploy.sh make up
生产 + 网关	./scripts/serve.sh --prod --gateway make start-pro	./scripts/serve.sh --prod --gateway --daemon make start-daemon-pro	—	./scripts/deploy.sh --gateway make up-pro

操作	本地模式	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	—

网关模式去除了 LangGraph 服务器进程——网关 API 直接通过异步任务处理智能体执行，并自行管理并发。

为何选择网关模式？

在标准模式下，DeerFlow 会同时运行一个专用的 LangGraph 平台服务器以及网关 API。这种架构虽然可行，但存在一些权衡：

	标准模式	网关模式
架构	网关（REST API）+ LangGraph（智能体运行时）	网关直接嵌入智能体运行时
并发控制	每个工作线程的 --n-jobs-per-worker（需许可证）	通过 --workers × 异步任务实现（无每工作线程上限限制）
容器/进程	4 个（前端、网关、LangGraph、Nginx）	3 个（前端、网关、Nginx）
资源消耗	较高（两个 Python 运行时）	较低（单个 Python 运行时）
LangGraph 平台许可证	生产镜像需要	无需
冷启动时间	较长（需初始化两个服务）	较短（只需初始化一个服务）

两种模式在功能上是等效的——相同的智能体、工具和技能在任一模式下均可正常工作。

Docker 生产部署

deploy.sh 支持分别构建和启动镜像。镜像本身与运行模式无关——运行时模式是在启动时指定的：

# 一步式（构建 + 启动）
deploy.sh                    # 标准模式（默认）
deploy.sh --gateway          # 网关模式

# 两步式（先构建一次，再以任意模式启动）
deploy.sh build              # 构建所有镜像
deploy.sh start              # 以标准模式启动
deploy.sh start --gateway    # 以网关模式启动

# 停止
deploy.sh down

高级功能

沙箱模式

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

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

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

请参阅 沙箱配置指南，以配置您偏好的模式。

MCP 服务器

DeerFlow 支持可配置的 MCP 服务器和技能，以扩展其功能。对于 HTTP/SSE 类型的 MCP 服务器，支持 OAuth token 流程（client_credentials、refresh_token）。详细说明请参阅 MCP 服务器指南。

IM 渠道

DeerFlow 支持从消息应用接收任务。配置完成后，渠道会自动启动，且无需任何公共 IP 地址。

渠道	传输方式	难度
Telegram	Bot API（长轮询）	简单
Slack	Socket Mode	中等
Feishu / Lark	WebSocket	中等
WeChat	Tencent iLink（长轮询）	中等
WeCom	WebSocket	中等

config.yaml 中的配置：

channels:
  # LangGraph 服务器 URL（默认：http://localhost:2024）
  langgraph_url: http://localhost:2024
  # 网关 API URL（默认：http://localhost:8001）
  gateway_url: http://localhost:8001

  # 可选：所有移动端渠道的全局会话默认值
  session:
    assistant_id: lead_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 Mode）
    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  # 此处也支持自定义代理名称
      context:
        thinking_enabled: false
      users:
        "123456789":
          assistant_id: vip-agent
          config:
            recursion_limit: 150
          context:
            thinking_enabled: true
            subagent_enabled: true

注意事项：

• 当 assistant_id: lead_agent 时，会直接调用默认的 LangGraph 助理。
• 如果将 assistant_id 设置为自定义代理名称，DeerFlow 仍会通过 lead_agent 进行路由，并将该值作为 agent_name 注入，从而使自定义代理的 SOUL/配置对 IM 渠道生效。

请在 .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

# WeChat iLink
WECHAT_BOT_TOKEN=your_ilink_bot_token
WECHAT_ILINK_BOT_ID=your_ilink_bot_id

# WeCom
WECOM_BOT_ID=你的 bot_id
WECOM_BOT_SECRET= 你的 bot_secret

Telegram 设置

1. 与 @BotFather 대화하여 /newbot를 보내고 HTTP API 토큰을 복사합니다.
2. .env 파일에 TELEGRAM_BOT_TOKEN을 설정하고 config.yaml에서 채널을 활성화합니다.

Slack 설정

1. api.slack.com/apps → 새 앱 만들기 → 처음부터 Slack 앱을 생성합니다.
2. OAuth 및 권한 섹션에서 봇 토큰 범위를 추가하세요: app_mentions:read, chat:write, im:history, im:read, im:write, files:write.
3. 소켓 모드를 활성화한 후, connections:write 범위가 있는 앱 수준 토큰(xapp-…)을 생성합니다.
4. 이벤트 구독 섹션에서 봇 이벤트를 구독하세요: app_mention, message.im.
5. .env 파일에 SLACK_BOT_TOKEN과 SLACK_APP_TOKEN을 설정하고 config.yaml에서 채널을 활성화합니다.

Feishu / Lark 설정

1. Feishu Open Platform에서 앱을 생성한 후 봇 기능을 활성화합니다.
2. 권한을 추가하세요: im:message, im:message.p2p_msg:readonly, im:resource.
3. 이벤트 섹션에서 im.message.receive_v1을 구독하고 장기 연결 모드를 선택합니다.
4. 앱 ID와 앱 시크릿을 복사합니다. .env 파일에 FEISHU_APP_ID와 FEISHU_APP_SECRET을 설정하고 config.yaml에서 채널을 활성화합니다.

WeChat 설정

1. config.yaml에서 wechat 채널을 활성화합니다.
2. .env 파일에 WECHAT_BOT_TOKEN을 설정하거나, 최초 QR 부팅을 위해 qrcode_login_enabled: true로 설정합니다.
3. bot_token이 없고 QR 부팅이 활성화된 경우, iLink에서 반환된 QR 코드 내용을 백엔드 로그에서 확인하고 바인딩 절차를 완료해야 합니다.
4. QR 절차가 성공하면 DeerFlow는 획득한 토큰을 state_dir에 저장하여 이후 재시작 시에도 사용할 수 있도록 합니다.
5. Docker Compose 배포 시에는 state_dir를 영구 저장소에 유지하여 get_updates_buf 커서와 저장된 인증 상태가 재시작 후에도 유지되도록 해야 합니다.

WeCom 설정

1. WeCom AI Bot 플랫폼에서 봇을 생성하고 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. 현재 통합은 인바운드 텍스트, 이미지 및 파일 메시지를 지원합니다. 에이전트가 생성한 최종 이미지/파일도 WeCom 대화로 다시 전송됩니다.

Docker Compose에서 DeerFlow가 실행될 때 IM 채널은 gateway 컨테이너 내부에서 작동합니다. 이 경우 channels.langgraph_url이나 channels.gateway_url을 localhost로 지정하지 말고, http://langgraph:2024 및 http://gateway:8001과 같은 컨테이너 서비스 이름을 사용하거나, DEER_FLOW_CHANNELS_LANGGRAPH_URL 및 DEER_FLOW_CHANNELS_GATEWAY_URL을 설정하세요.

명령어

채널이 연결되면 채팅에서 직접 DeerFlow와 상호작용할 수 있습니다:

명령어	설명
/new	새로운 대화 시작
/status	현재 스레드 정보 표시
/models	사용 가능한 모델 목록
/memory	메모리 보기
/help	도움말 표시

명령어 접두사가 없는 메시지는 일반 채팅으로 간주되며, DeerFlow는 스레드를 생성하고 대화형으로 응답합니다.

LangSmith 추적

DeerFlow에는 관측성을 위한 LangSmith 통합이 기본 탑재되어 있습니다. 활성화하면 모든 LLM 호출, 에이전트 실행 및 툴 실행이 추적되어 LangSmith 대시보드에서 확인할 수 있습니다.

.env 파일에 다음을 추가하세요:

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

Langfuse 추적

DeerFlow는 LangChain 호환 실행을 위한 Langfuse 관측성도 지원합니다.

.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를 설정하세요.

딥 리서치에서 슈퍼 에이전트 하니스로

DeerFlow는 딥 리서치 프레임워크로 시작되었으며, 커뮤니티는 이를 적극적으로 활용해 왔습니다. 출시 이후 개발자들은 연구를 넘어 데이터 파이프라인 구축, 슬라이드덱 생성, 대시보드 구축, 콘텐츠 워크플로우 자동화 등 우리가 예상하지 못했던 다양한 작업을 수행해 왔습니다.

이는 우리에게 중요한 사실을 알려주었습니다: DeerFlow는 단순한 연구 도구가 아니었습니다. 그것은 에이전트가 실제로 업무를 수행할 수 있도록 인프라를 제공하는 런타임인 하니스였습니다.

그래서 우리는 처음부터 다시 설계했습니다.

DeerFlow 2.0은 더 이상 사용자가 직접 구성해야 하는 프레임워크가 아닙니다. 배터리가 포함되어 있으며 완전히 확장 가능한 슈퍼 에이전트 하니스입니다. LangGraph와 LangChain을 기반으로 제작된 이 제품은 에이전트가 바로 사용할 수 있도록 파일 시스템, 메모리, 스킬, 샌드박싱 인식 실행 기능, 그리고 복잡한 다단계 작업을 위해 하위 에이전트를 계획하고 생성할 수 있는 기능을 기본 탑재하고 있습니다.

그대로 사용하거나, 필요한 부분만 떼어내어 자신만의 방식으로 활용할 수 있습니다.

핵심 기능

스킬 & 툴

DeerFlow가 거의 모든 일을 할 수 있게 만드는 것은 바로 스킬입니다.

표준 에이전트 스킬은 구조화된 기능 모듈로, 워크플로, 모범 사례 및 관련 자료를 정의하는 Markdown 파일입니다. DeerFlow는 연구, 보고서 작성, 슬라이드 생성, 웹 페이지 제작, 이미지 및 비디오 생성 등을 위한 기본 스킬을 제공합니다. 그러나 진정한 강점은 확장성에 있습니다: 사용자 고유의 스킬을 추가하거나 기본 스킬을 교체하거나, 여러 스킬을 결합하여 복합적인 워크플로를 구성할 수 있습니다.

스킬은 작업에 필요할 때만 순차적으로 로드됩니다. 이는 컨텍스트 윈도우를 효율적으로 유지하고, 토큰 수에 민감한 모델에서도 DeerFlow가 원활하게 작동하도록 합니다.

게이트웨이를 통해 .skill 아카이브를 설치할 때, DeerFlow는 유효한 외부 스킬을 거부하는 대신 version, author, compatibility와 같은 표준 옵션 프론트마터 메타데이터를 받아들입니다.

툴 역시 동일한 개념을 따릅니다. DeerFlow는 웹 검색, 웹 가져오기, 파일 작업, bash 실행 등의 기본 툴셋을 제공하며, MCP 서버와 Python 함수를 통해 맞춤형 툴을 지원합니다. 원하는 대로 교체하거나 추가할 수 있습니다.

게이트웨이에서 생성되는 후속 제안은 이제 JSON 배열 응답을 파싱하기 전에 일반 문자열 모델 출력과 블록/목록 형식의 리치 콘텐츠를 정규화하여, 제공업체 특정 콘텐츠 래퍼로 인해 제안이 무시되는 현상을 방지합니다.

# 沙箱容器内的路径
/mnt/skills/public
├── research/SKILL.md
├── report-generation/SKILL.md
├── slide-creation/SKILL.md
├── web-page/SKILL.md
└── image-generation/SKILL.md

/mnt/skills/custom
└── your-custom-skill/SKILL.md      ← 你的技能

Claude Code 集成

claude-to-deerflow 技能使你能够直接从 Claude Code 与正在运行的 DeerFlow 实例交互。发送研究任务、检查状态、管理线程——所有这些都不需要离开终端。

安装该技能：

npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow

然后确保 DeerFlow 正在运行（默认地址为 http://localhost:2026），并在 Claude Code 中使用 /claude-to-deerflow 命令。

你可以做的事情：

• 向 DeerFlow 发送消息并获取流式响应
• 选择执行模式：flash（快速）、standard、pro（规划）、ultra（子代理）
• 检查 DeerFlow 的健康状况，列出模型/技能/代理
• 管理线程和对话历史
• 上传文件进行分析

环境变量（可选，用于自定义端点）：

DEERFLOW_URL=http://localhost:2026            # 统一代理基础 URL
DEERFLOW_GATEWAY_URL=http://localhost:2026    # Gateway API
DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph  # LangGraph API

完整 API 参考请参阅 skills/public/claude-to-deerflow/SKILL.md。

子代理

复杂的任务很少能在一次处理中完成。DeerFlow 会将它们分解。

主代理可以随时动态生成子代理——每个子代理都有自己的作用域上下文、工具和终止条件。子代理在可能的情况下并行运行，返回结构化的结果，而主代理则将所有内容综合成一个连贯的输出。

这就是 DeerFlow 处理需要数分钟到数小时的任务的方式：一项研究任务可能会扩展为十几个子代理，每个子代理探索不同的角度，然后汇聚成一份报告、一个网站或带有生成视觉效果的幻灯片演示文稿。一个统筹者，多双手协作。

沙箱与文件系统

DeerFlow 不只是“谈论”如何做事，它有自己的计算机。

每个任务都会获得一个独立的执行环境，包含完整的文件系统视图——技能、工作区、上传文件、输出文件。代理可以读取、写入和编辑文件。它可以查看图像，并在安全配置下执行 Shell 命令。

使用 AioSandboxProvider 时，Shell 执行会在隔离的容器内运行。而使用 LocalSandboxProvider 时，文件工具仍然映射到主机上的线程专用目录，但主机的 bash 默认被禁用，因为它不是一个安全的隔离边界。仅在完全可信的本地工作流中才应重新启用主机的 bash。

这正是拥有工具访问权限的聊天机器人与拥有实际执行环境的代理之间的区别。

# 沙箱容器内的路径
/mnt/user-data/
├── uploads/          ← 你的文件
├── workspace/        ← 代理的工作目录
└── outputs/          ← 最终交付物

上下文工程

隔离的子代理上下文：每个子代理都在自己独立的上下文中运行。这意味着子代理无法看到主代理或其他子代理的上下文。这一点很重要，可以确保子代理专注于手头的任务，而不受主代理或其他子代理上下文的干扰。

总结：在一个会话中，DeerFlow 会积极管理上下文——总结已完成的子任务，将中间结果卸载到文件系统，压缩不再立即相关的部分。这样它就能在长时间的多步骤任务中保持高效，而不会超出上下文窗口限制。

严格的工具调用恢复：当提供者或中间件中断工具调用循环时，DeerFlow 现在会在强制停止的助手消息中剥离提供者级别的原始工具调用元数据，并在下次模型调用之前为悬空的工具调用注入占位符结果。这样做可以防止严格验证 tool_call_id 序列的 OpenAI 兼容推理模型因历史记录格式错误而失败。

长期记忆

大多数代理在对话结束时就会忘记一切。而 DeerFlow 则会记住。

在不同会话之间，DeerFlow 会构建一个持久的记忆库，记录你的个人资料、偏好和积累的知识。你使用得越多，它就越了解你——你的写作风格、你的技术栈、你经常重复的工作流程。记忆存储在本地，始终由你掌控。

现在，记忆更新会在应用时跳过重复的事实条目，因此重复的偏好和上下文不会在不同会话中无休止地累积。

推荐模型

DeerFlow 是模型无关的——它适用于任何实现了 OpenAI 兼容 API 的 LLM。不过，它在以下类型的模型上表现最佳：

• 长上下文窗口（10万+ tokens），适合深度研究和多步骤任务
• 推理能力，用于自适应规划和复杂分解
• 多模态输入，用于图像理解和视频解析
• 强大的工具使用能力，以实现可靠的函数调用和结构化输出

嵌入式 Python 客户端

DeerFlow 可以作为嵌入式 Python 库使用，而无需运行完整的 HTTP 服务。DeerFlowClient 提供对所有代理和 Gateway 功能的直接进程内访问，返回与 HTTP Gateway API 相同的响应模式。HTTP Gateway 还公开了 DELETE /api/threads/{thread_id} 端点，用于在 LangGraph 线程本身已被删除后，移除 DeerFlow 管理的本地线程数据：

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# 对话
response = client.chat("帮我分析这篇论文", thread_id="my-thread")

# 流式传输（LangGraph SSE 协议：values、messages-tuple、end）
for event in client.stream("hello"):
    if event.type == "messages-tuple" 和 event.data.get("type") == "ai":
        print(event.data["content"])

# 配置与管理——返回与 Gateway 对齐的字典
models = client.list_models()        # {"models": [...]}
skills = client.list_skills()        # {"skills": [...]}
client.update_skill("web-search", enabled=True)
client.upload_files("thread-1", ["./report.pdf"])  # {"success": True, "files": [...]}

所有返回字典的方法都会在 CI 中根据 Gateway Pydantic 响应模型进行验证（TestGatewayConformance），以确保嵌入式客户端与 HTTP API 模式保持同步。完整 API 文档请参阅 backend/packages/harness/deerflow/client.py。

文档

• 贡献指南 - 开发环境设置和工作流程
• 配置指南 - 设置和配置说明
• 架构概述 - 技术架构细节
• 后端架构 - 后端架构和 API 参考

⚠️ 安全提示

部署不当可能引入安全风险

DeerFlow 具有关键的高权限能力，包括 系统命令执行、资源操作和业务逻辑调用，默认设计为 部署在本地可信环境中（仅可通过 127.0.0.1 回环接口访问）。如果您在不可信环境（如局域网、公有云服务器或其他多端点可访问的环境）中部署代理，且未采取严格的安全措施，则可能带来以下安全风险：

• 未经授权的非法调用：代理功能可能被未经授权的第三方或恶意网络扫描器发现，从而触发大量未经许可的请求，执行系统命令、文件读写等高风险操作，进而导致严重的安全后果。
• 合规与法律风险：若代理被非法调用以实施网络攻击、数据窃取或其他违法行为，可能会引发法律责任和合规风险。

安全建议

注意：我们强烈建议将 DeerFlow 部署在本地可信网络环境中。 如果需要跨设备或跨网络部署，必须实施严格的安全措施，例如：

• IP 白名单：使用 iptables，或部署带有访问控制列表（ACL）的硬件防火墙/交换机，配置 IP 白名单规则，拒绝来自其他所有 IP 地址的访问。
• 认证网关：配置反向代理（如 nginx），并启用强身份验证机制，阻止任何未认证的访问。
• 网络隔离：在条件允许的情况下，将代理与受信任设备放置在同一专用 VLAN 中，与其他网络设备隔离。
• 保持更新：持续关注 DeerFlow 的安全功能更新。

贡献说明

我们欢迎各位的贡献！请参阅 CONTRIBUTING.md 了解开发环境搭建、工作流程及相关指南。

回归测试覆盖范围包括 Docker 沙箱模式检测以及 backend/tests/ 中 provisioner kubeconfig-path 处理相关的测试用例。目前，网关在提供构建产物时，会强制将活动 Web 内容类型（text/html、application/xhtml+xml、image/svg+xml）作为附件下载，而非内联渲染，从而降低生成产物的 XSS 风险。

许可证

本项目为开源项目，采用 MIT 许可证 开放源代码。

致谢

DeerFlow 的开发建立在开源社区卓越工作的基础之上。我们由衷感谢所有为 DeerFlow 的实现做出贡献的项目和开发者们。可以说，我们正是站在巨人的肩膀上才得以完成这一项目。

在此，我们特别感谢以下项目提供的宝贵支持：

• LangChain：其出色的框架为我们提供了强大的 LLM 交互与链式处理能力，实现了无缝集成与高效功能。
• LangGraph：他们在多智能体编排方面的创新方法，对 DeerFlow 精密工作流的实现起到了至关重要的作用。

这些项目充分展现了开源协作的变革力量，我们很荣幸能够在此基础上继续前行。

主要贡献者

衷心感谢 DeerFlow 的核心作者们，是他们的远见卓识、满腔热忱与不懈努力，才让这个项目得以诞生：

• Daniel Walnut
• Henry Li

你们坚定不移的承诺与专业能力，是 DeerFlow 取得成功的关键动力。我们深感荣幸能与您们携手共进，引领这一旅程。

星标历史

DeerFlow 2.0 快速上手指南

DeerFlow (Deep Exploration and Efficient Research Flow) 是一个开源的超级智能体框架（Super Agent Harness），能够编排子智能体、记忆模块和沙箱环境，通过可扩展的技能执行复杂任务。

1. 环境准备

系统要求

• 操作系统: 推荐 Linux (Ubuntu/Debian) 或 macOS。Windows 用户建议使用 WSL2。
• Python: 3.12 或更高版本。
• Node.js: 22 或更高版本。
• Docker: 推荐安装 Docker Desktop 或 Docker Engine（用于沙箱隔离）。

硬件建议

• 本地开发/评估: 至少 4 vCPU, 8 GB RAM, 20 GB 可用 SSD。
• 长期运行/多智能体: 推荐 8 vCPU, 16 GB RAM 或更高。

前置依赖

确保已安装 git, make, docker (可选但推荐)。

2. 安装步骤

第一步：克隆项目

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

第二步：运行配置向导

在项目根目录下运行以下命令，启动交互式配置向导。它将引导你选择大模型提供商、配置 API Key 并生成 config.yaml 和 .env 文件。

make setup

提示：

• 该过程约需 2 分钟。
• 如果你在中国大陆，建议在运行前设置国内镜像加速环境变量，以提升依赖下载速度：

  export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
  export NPM_REGISTRY=https://registry.npmmirror.com
  

• 如需手动检查配置状态，可随时运行 make doctor。

第三步：启动服务 (推荐 Docker 模式)

初始化沙箱镜像（首次运行或镜像更新时执行）：

make docker-init

启动服务：

make docker-start

注：make docker-start 会根据 config.yaml 自动检测是否启用沙箱模式。后端进程会自动热重载配置变更，开发时无需手动重启。

Linux 用户注意：若遇到 permission denied 连接 Docker socket 错误，请将当前用户加入 docker 组并重新登录： sudo usermod -aG docker $USER

3. 基本使用

配置模型

在运行前，请确保已在 .env 文件中配置好大模型 API Key。DeerFlow 支持多种模型，推荐使用 Doubao-Seed-2.0-Code, DeepSeek v3.2 或 Kimi 2.5 以获得最佳代码与推理性能。

你可以在 config.yaml 中手动指定模型（示例）：

models:
  - name: deepseek-v3
    display_name: DeepSeek V3
    use: langchain_openai:ChatOpenAI
    model: deepseek-chat
    api_key: $DEEPSEEK_API_KEY
    base_url: https://api.deepseek.com/v1

运行智能体

启动服务后，DeerFlow 将根据你的配置运行。你可以通过以下方式与之交互：

1. 命令行交互: 直接在终端输入自然语言指令，DeerFlow 将自动规划任务、调用子智能体、搜索信息（如配置了 InfoQuest 或 Tavily）并执行代码。
2. 集成 InfoQuest: DeerFlow 已集成字节火山引擎开发的智能搜索工具 InfoQuest，可在配置中启用以增强联网检索能力。

验证安装

运行以下命令验证环境是否正常：

make doctor

如果一切正常，系统将输出当前的配置摘要和健康状态。

---

更多高级功能（如 MCP Server、LangSmith 追踪、自定义沙箱等）请参考官方文档或访问 DeerFlow 官网 查看实时演示。