DeerFlow 2.0 完全指南：从 Deep Research 到可扩展 Super Agent Harness 的部署、配置与运行原理

2026-09-07 16:40:31作者：田桥桑Industrious

An open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.

项目地址：https://gitcode.com/GitHub_Trending/de/deer-flow

导读

DeerFlow 是一个基于 LangGraph/LangChain 构建的开源 super agent harness：它将 sub-agents、memory、sandbox 与可扩展的 skills 组织成一个开箱即用的运行时，让 agent 能够完成从深度研究、编码到内容创作等分钟级到小时级的复杂长程任务。本文以官方中文 README 为骨架，结合仓库内的 config.example.yaml、Makefile 与源码实现，完整覆盖快速安装、模型配置、Docker/本地运行、Sandbox、IM 渠道、链路追踪、定时任务、TUI 等全部内容；读完你既可以照着跑起一个完整实例，也能理解其底层「执行环境 + 上下文管理 + 委派」的设计脉络。

一、DeerFlow 2.0 是什么：从框架到 Harness

DeerFlow 的名字是 Deep Exploration and Efficient Research Flow 的缩写。它的前身是一个 Deep Research（深度研究）框架，社区在使用过程中把它扩展到了数据流水线、演示文稿生成、dashboard 搭建、内容流程自动化等远超「研究」的方向，从而推动项目在 2.0 版做了彻底重写——与 v1 不共用任何代码，当前主要开发已完全转向 2.0。

与「需要自己拼装的 framework」不同，DeerFlow 2.0 定位为一个开箱即用、又足够可扩展的 harness：

基于 LangGraph 和 LangChain 构建（README 明确致谢这两个项目，分别支撑了多 agent 编排与 LLM 交互/chain 能力）；
默认自带 agent 真正需要的关键运行时能力：文件系统、memory、skills、sandbox 执行环境，以及为复杂多步骤任务做规划、拉起 sub-agents 的能力；
每个任务运行在隔离的 Docker 容器里，拥有完整的文件系统（skills、workspace、uploads、outputs），可读可写、可执行 bash、可查看图片，全过程可审计、跨 session 不互相污染。

在仓库中，agent 运行时嵌入在 Gateway 内运行，/api/langgraph/* 路径会由 nginx 重写到 Gateway 的 LangGraph-compatible API。因此用户实际看到的只有统一的入口：http://localhost:2026。

二、快速开始：安装、配置与运行

2.1 一句话交给 Coding Agent 安装

如果你在用 Claude Code、Codex、Cursor、Windsurf 等 coding agent，可以把下面这句话直接发给它，让 agent 自动完成克隆与初始化：

如果还没 clone DeerFlow，就先 clone，然后按照仓库根目录的 Install.md 把它的本地开发环境初始化好

这条提示词会引导 coding agent：需要时先克隆仓库，优先选择 Docker 完成初始化，并在结束时告诉你下一条启动命令，以及还缺哪些配置需要补充。

2.2 交互式安装向导（推荐）

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

make setup

这会启动交互式向导（对应实现为 scripts/setup_wizard.py），引导你选择 LLM provider、可选的 web 搜索工具，以及 sandbox 模式、bash 权限、文件写入等执行/安全偏好，然后：

生成一份最小化的 config.yaml；
把 API key 写入 .env；
整个过程大约 2 分钟完成。

配置与排障相关的三条辅助命令：

命令	作用
`make doctor`	检查配置与系统环境，给出可执行的修复建议
`make support-bundle`	生成脱敏的 issue 诊断包（详见下文）
`make config`	直接复制完整的示例模板（若已有 config 则中止，避免覆盖）
`make config-upgrade`	将 `config.example.yaml` 中新字段合并进本地 `config.yaml`

make doctor / make support-bundle 均封装在 scripts/doctor.py 与 scripts/support_bundle.py。support-bundle 会在 .deer-flow/support-bundles/ 下生成 *-issue-summary.md（提交 issue 用）、面向 AI 代填的 *-issue-draft.md（含 REQUIRED 占位符）以及可选的证据 zip 与 triage.json；bundle 只包含脱敏后的诊断信息与文件 manifest，不包含 .env、原始对话消息或用户文件内容。

2.3 进阶 / 手动配置

如果你更想直接编辑 config.yaml，可改用 make config 复制完整示例模板。完整参考以根目录 config.example.yaml 为准，其中包含 CLI-backed provider（Codex CLI、Claude Code OAuth）、OpenRouter、Responses API 等更多配置。该文件当前声明 config_version: 40，配置 schema 变更时需要运行 make config-upgrade 合并新字段。

手动模型配置示例（来自 README，可整体放入 config.yaml 的 models: 列表）：

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

关键解读（结合 config.example.yaml 与源码 backend/packages/harness/deerflow/models）：

use 是点分导入路径，格式为 包.模块:类名。OpenAI 兼容网关（OpenRouter、Novita 等）用 langchain_openai:ChatOpenAI + base_url；需要保留推理模型 reasoning_content 字段多轮回放时改用 deerflow.models.patched_openai:PatchedChatOpenAI。
Responses API：继续用 langchain_openai:ChatOpenAI，并设置 use_responses_api: true 与 output_version: responses/v1。
vLLM 0.19.0：使用 deerflow.models.vllm_provider:VllmChatModel；对 Qwen 风格推理模型通过 extra_body.chat_template_kwargs.enable_thinking 开关推理，并在多轮 tool-call 中保留 vLLM 非标准的 reasoning 字段。旧版 thinking 配置会自动规范化以向后兼容。本地 vLLM 部署若接受任意非空 key，可将 VLLM_API_KEY 设为占位值；部分推理模型还要求启动 vLLM 时加 --reasoning-parser ...。
thinking 与推理配置：supports_thinking: true 才能让 UI 的 thinking 开关生效；when_thinking_enabled / when_thinking_disabled 分别注入开/关时的 extra_body。Z.AI GLM-5.3-Flash 这类「强制 thinking」模型需按 config.example.yaml 中注释说明保持 thinking 恒开并屏蔽通用 effort 选择器。
各厂商适配器都有对应源码：patched_deepseek.py、patched_mimo.py、patched_minimax.py、patched_stepfun.py、vllm_provider.py、claude_provider.py、openai_codex_provider.py、mindie_provider.py 均位于 backend models 目录，分别处理各家 thinking 字段、reasoning 回放、用户名校验等兼容问题。

CLI-backed provider 配置示例：

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 条目与 model provider 是分开配置的——如果你配置了 acp_agents.codex，请把它指向 Codex ACP 适配器（如 npx -y @zed-industries/codex-acp）；

MiniMax Code 原生支持 ACP，无需适配器：

npm install --global @minimax-ai/code
mcode login

acp_agents:
  mcode:
    command: mcode
    args: ["acp"]
    description: MiniMax Code for implementation, refactoring, debugging, and repository tasks
    auto_approve_permissions: false

mcode 必须位于 Gateway 进程的 PATH 中；处理不可信任务时保持 auto_approve_permissions: false，只有任务可信且确需 MCode 改文件/执行命令时才启用。

macOS 上如需显式导出 Claude Code 认证：

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

API key 也可手动写入 .env 文件（推荐）或在 shell 导出：

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

2.4 部署建议与资源规划

根据 README 建议，可按资源档位选择运行方式（仅覆盖 DeerFlow 本身；本地大模型需单独预留资源）：

部署场景	起步配置	推荐配置	说明
本地体验 / `make dev`	4 vCPU、8 GB 内存、20 GB SSD 可用空间	8 vCPU、16 GB 内存	适合单开发者或单个轻量会话，且模型走外部 API。`2 核 / 4 GB` 通常跑不稳。
Docker 开发 / `make docker-start`	4 vCPU、8 GB 内存、25 GB SSD 可用空间	8 vCPU、16 GB 内存	镜像构建、源码挂载与 sandbox 容器都会更吃资源。
长期运行服务 / `make up`	8 vCPU、16 GB 内存、40 GB SSD 可用空间	16 vCPU、32 GB 内存	更适合共享环境、多 agent 任务、报告生成或重 sandbox 负载。

另外两条实用原则：持续运行的服务更推荐 Linux + Docker，macOS/Windows 适合作为开发或体验环境；CPU/内存长期打满时先降低并发会话与重任务数量，再考虑升档。

2.5 方式一：Docker 运行（推荐）

前置条件：Docker Desktop / Docker Engine + Docker Compose v2.24+（更旧的 Compose 客户端无法解析 docker/docker-compose-dev.yaml 里的可选 env_file 语法）。

开发模式（支持热更新、挂载源码）：

make docker-init    # 拉取 sandbox 镜像（首次或镜像更新时执行）
make docker-start   # 启动服务（根据 config.yaml 自动判断 sandbox 模式）

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

生产模式（本地构建镜像，挂载运行期配置与数据）：

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

更完整的 Docker 开发说明见 CONTRIBUTING.md。上述命令的目标定义在 Makefile 中，分别经由 scripts/docker.sh 与 scripts/deploy.sh 执行。

2.6 方式二：本地开发

前提是先完成配置步骤（make setup）。make dev 需要有效配置文件，默认读取项目根目录的 config.yaml。关键环境变量：

环境变量	作用	默认值
`DEER_FLOW_PROJECT_ROOT`	显式指定项目根目录	—
`DEER_FLOW_CONFIG_PATH`	指向某个具体配置文件	`config.yaml`
`DEER_FLOW_HOME`	覆盖运行期状态目录	项目根下的 `.deer-flow`
`DEER_FLOW_SKILLS_PATH`	覆盖 skills 读取目录	项目根下的 `skills/`

启动前先运行 make doctor 校验配置。在 Windows 上请使用 Git Bash 运行本地开发流程——基于 bash 的服务脚本不支持原生 cmd.exe/PowerShell，且 WSL 不保证可用（部分脚本依赖 Git for Windows 的 cygpath 等工具）。

make check        # 校验 Node.js 22+、pnpm、uv、nginx
make install      # 安装 backend + frontend 依赖
make setup-sandbox  # （可选）若使用 Docker/Container sandbox，建议预拉镜像
make dev          # 启动全部服务

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

三、进阶配置

3.1 Sandbox 模式

DeerFlow 通过 sandbox.use 支持多种执行后端（详见 config.example.yaml 的 Sandbox 段与 backend/docs/CONFIGURATION.md）：

模式	实现类	说明
本地执行（默认）	`deerflow.sandbox.local:LocalSandboxProvider`	直接在宿主机执行；`allow_host_bash` 默认 `false`，需显式开启
Docker / Apple Container	`deerflow.community.aio_sandbox:AioSandboxProvider`	隔离容器；macOS 上优先 Apple Container，其他平台用 Docker
Kubernetes（provisioner）	同上 + `provisioner_url`	每个 sandbox 一个 k3s Pod，隔离性与扩展性更好
BoxLite 微 VM	`deerflow.community.boxlite:BoxliteProvider`	需要 KVM / Hypervisor.framework
Tenki 云微 VM	`deerflow.community.tenki:TenkiSandboxProvider`	云端微 VM，warm pool 复用
OpenSandbox 远程	`deerflow.community.opensandbox:OpenSandboxProvider`	远程沙箱服务

容器化 AIO sandbox 的常用可选参数包括：image（默认 enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox，建议固定到带 /v1/bash/* 路由的具体版本，如 1.11.0 多架构镜像）、port（默认 8080）、replicas（最大并发容器数，默认 3，超过时按 LRU 淘汰）、network.mode（open/isolated/allowlist，限制模式需要 Docker Engine 28+）、mounts、environment，以及多实例共享容器后端时必须的 ownership.type: redis。

Docker 开发时，服务启动行为遵循 config.yaml 里的 sandbox 模式；在 Local / Docker 模式下不会启动 provisioner。源码中的容器编排与网络策略实现位于 backend sandbox 相关模块，网络限制的具体配置项可参考 config.example.yaml 中的注释与后端 CONFIGURATION 文档。

3.2 MCP Server

DeerFlow 支持可配置的 MCP Server 和 skills 来扩展能力，对 HTTP/SSE MCP Server 支持 OAuth token 流程（client_credentials、refresh_token）。详细说明见 backend/docs/MCP_SERVER.md。

值得注意的是（README 安全章节提醒）：管理员注册的 stdio 类型 MCP server 命令会在 Gateway 容器内执行，因此该能力属于高权限操作（详见下文「安全使用」）。

3.3 IM 渠道

DeerFlow 支持从即时通讯应用接收任务，配置完成后对应渠道自动启动，且都不需要公网 IP（Telegram/Slack 走 long-polling 或 Socket Mode，飞书/企业微信/钉钉走 WebSocket/Stream 长连接）。另外在 workspace UI 启用 channel_connections 后，已登录用户可在 Settings > Channels 绑定自有渠道账号，复用现有 channels.* 出站传输，入站消息以所连接用户身份运行，详见 backend/docs/IM_CHANNEL_CONNECTIONS.md。

渠道	传输方式	上手难度
Telegram	Bot API（long-polling）	简单
Slack	Socket Mode	中等
Feishu / Lark	WebSocket	中等
WeChat	Tencent iLink（long-polling）	中等
企业微信智能机器人	WebSocket	中等
钉钉	Stream Push（WebSocket）	中等

config.yaml 中的配置示例（README 原样内容，含注释）：

channels:
  # LangGraph-compatible Gateway API base URL（默认：http://localhost:8001/api）
  langgraph_url: http://localhost:8001/api
  # Gateway API URL（默认：http://localhost:8001）
  gateway_url: http://localhost:8001

  # 可选：所有移动端渠道共用的全局 session 默认值
  session:
    assistant_id: lead_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 Mode）
    allowed_users: []               # 留空表示允许所有人

  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []               # 留空表示允许所有人

    # 可选：按渠道 / 按用户单独覆盖 session 配置
    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

  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

  dingtalk:
    enabled: true
    client_id: $DINGTALK_CLIENT_ID             # 钉钉开放平台 ClientId
    client_secret: $DINGTALK_CLIENT_SECRET     # 钉钉开放平台 ClientSecret
    allowed_users: []                          # 留空表示允许所有人
    card_template_id: ""                       # 可选：AI 卡片模板 ID，用于流式打字机效果

说明：

assistant_id: lead_agent 直接调用默认的 LangGraph assistant；
若 assistant_id 填自定义 agent 名，DeerFlow 仍走 lead_agent，同时将该值注入为 agent_name，使对应 agent 的 SOUL 与配置在 IM 渠道生效。

在 .env 里设置对应 key：

# 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_BOT_ID=your_bot_id
WECOM_BOT_SECRET=your_bot_secret

# 钉钉
DINGTALK_CLIENT_ID=your_client_id
DINGTALK_CLIENT_SECRET=your_client_secret

各渠道开通要点（来自 README）：

Telegram：向 @BotFather 发 /newbot 获取 HTTP API token → 设置 TELEGRAM_BOT_TOKEN 并启用渠道。机器人支持入站文本、图片与文档（可带说明文字）；托管版 Bot API 单个附件下载上限 20 MB。
Slack：在 api.slack.com/apps 创建 App，于 OAuth & Permissions 添加 Bot Token Scopes：app_mentions:read、chat:write、im:history、im:read、im:write、files:write；启用 Socket Mode 并生成带 connections:write 的 App-Level Token（xapp-...）；在 Event Subscriptions 订阅 app_mention、message.im。
Feishu / Lark：开放平台创建应用并启用 Bot；添加权限 im:message、im:message.p2p_msg:readonly、im:resource；事件订阅 im.message.receive_v1 且连接方式选长连接；填入 App ID/Secret 并启用渠道。
WeChat：启用 wechat 渠道并设置 WECHAT_BOT_TOKEN，或把 qrcode_login_enabled: true 走扫码登录引导；成功登录后 token 持久化到 state_dir（Docker Compose 部署需把它放在持久化卷上，以保留 get_updates_buf 游标与登录状态）。
企业微信智能机器人：创建机器人获取 bot_id/bot_secret；安装后端依赖时确保包含 wecom-aibot-python-sdk，渠道经 WebSocket 长连接收消息，无需公网回调；当前支持文本/图片/文件入站，agent 的最终图片/文件也会回传会话。
钉钉：开放平台创建应用并启用机器人，消息接收模式设为 Stream 模式；设置 Client ID/Secret。可选：在钉钉卡片平台创建 AI 卡片模板（打字机流式效果），把 card_template_id 设为模板 ID，并申请 Card.Streaming.Write、Card.Instance.Write 权限。

IM 渠道内置命令：

命令	说明
`/new`	开启新对话
`/status`	查看当前 thread 信息
`/models`	列出可用模型
`/memory`	查看 memory
`/help`	查看帮助

没有命令前缀的消息会被当作普通聊天处理，DeerFlow 自动创建 thread 并以对话方式回复。相关渠道实现位于 backend/app/channels（telegram.py、slack.py、feishu.py、dingtalk.py、wechat.py、wecom.py、discord.py、buzz.py 等）。

3.4 链路追踪：LangSmith 与 Langfuse

DeerFlow 内置两个可观测性集成，启用后所有 LLM 调用、agent 运行与工具执行都会被追踪。

LangSmith：在 .env 添加

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

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 指向你的部署地址。

链路关联字段（README 说明）：每次 agent 运行都会标注 Langfuse 保留追踪属性，让 Sessions 与 Users 页面自动填充数据：

session_id = LangGraph 的 thread_id——同一会话的所有 trace 归为一组；
user_id = 来自 get_effective_user_id() 的有效用户（无鉴权模式回退为 default）；
trace_name = assistant id（默认为 lead-agent）；
tags = [env:<DEER_FLOW_ENV>, model:<model_name>]（未设置时省略）；
metadata.deerflow_trace_id = DeerFlow 请求关联 id，始终与同一请求返回的 X-Trace-Id 响应头一致（logging.enhance.enabled 仅控制该 id 是否打印到日志）。

这些字段在 graph 调用根部注入 RunnableConfig.metadata，同时覆盖 Gateway 路径（runtime/runs/worker.py::run_agent）与内嵌路径（client.py::DeerFlowClient.stream），因此任何兼容 LangChain 的 callback 都能读取。设置 DEER_FLOW_ENV（或 ENVIRONMENT）可为 trace 打环境标签。

同时启用两者时，DeerFlow 会挂载两个追踪 callback 并把相同模型活动上报到两套系统；某个 provider 被显式启用但缺凭据、或其 callback 初始化失败时，会在创建模型/初始化追踪阶段快速失败（fail fast），错误信息会指明导致失败的 provider。Docker 部署默认关闭追踪。

四、核心特性深度解析

4.1 Skills 与 Tools

Skills 是 DeerFlow 能做「几乎任何事」的关键。 标准 Agent Skill 是结构化能力模块，通常就是一个 Markdown 文件，里面定义了工作流、最佳实践与参考资源。仓库内置的 public skills 位于 skills/public，覆盖研究（deep-research、systematic-literature-review、github-deep-research、academic-paper-review）、数据分析（data-analysis、chart-visualization）、内容生成（ppt-generation、newsletter-generation、podcast-generation、video-generation、image-generation）、前端设计（frontend-design、web-design-guidelines）、代码辅助（code-documentation、claude-to-deerflow）等方向。你可以新增、替换或组合它们为复合工作流。

在 sandbox 容器内，skills 挂载结构示意如下（具体以实际 skills/ 目录为准）：

# sandbox 容器内的路径
/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      ← 你的 skill

（skills.container_path 默认 /mnt/skills，可在 config.example.yaml 中修改；custom 目录由 /mnt/skills/custom 承载用户自建 skill。）

Skills 采用按需渐进加载，只有任务确实需要时才把 skill 内容装入上下文，避免一次性塞满上下文窗口——这对 token 敏感的模型尤其友好。config.example.yaml 中还提供 skills.deferred_discovery: true 选项：开启后系统提示词只出现 <skill_index> 技能名列表，LLM 通过 describe_skill 工具按需获取细节，进一步压缩系统提示词并利于 prefix caching。通过 Gateway 安装 .skill 压缩包时接受标准可选 frontmatter（如 version、author、compatibility），不会拒收合法的外部 skill。

Tools 同理可替换、可扩展。默认核心工具（见 config.example.yaml tools: 段）：web_search（默认 DuckDuckGo，无需 key）、web_fetch（默认 Jina reader）、image_search（DuckDuckGo）、文件类 ls/read_file/glob/grep/write_file/str_replace，以及按需激活的 bash。同一种工具可切换后端：web_search 还支持 Tavily、Serper、Serply、Brave、SearXNG、Exa、Firecrawl、GroundRoute、InfoQuest、腾讯云 WSA、fastCRW 等 provider（各自是 deerflow.community.* 下的 Python 工具模块，并有对应测试）；同时支持通过 MCP Server 与 Python 函数扩展自定义工具。

工具列表按 group 组织（web、file:read、file:write、bash、browser、knowledge），用于权限与访问控制。config.example.yaml 还展示了 knowledge_search 工具对接 RAGFlow / LightRAG 两种只读知识库后端的完整参数（base_url、top_k、max_total_chars 等）。

4.2 Claude Code 集成

借助 claude-to-deerflow skill，你可以直接在 Claude Code 里与正在运行的 DeerFlow 交互，无需离开终端即可下发研究任务、查看状态、管理 threads。

安装 skill：

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（sub-agents 模式）；
检查健康状态，列出 models / skills / agents；
管理 threads 与会话历史；
上传文件做分析。

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

DEERFLOW_URL=http://localhost:2026            # 统一代理基地址
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。此外，Web UI 输入框还支持浏览器侧语音听写（Web Speech API），语音在本地转写为草稿后仅提交文本。

4.3 Session Goals

用 /goal <完成条件> 为当前 thread 绑定「激活态」完成条件。goal 是 thread 维度状态而非 skill 激活，会跨轮次持续生效，直到被判定满足或手动清除。

/goal finish the implementation and make all tests pass
/goal              # 查看当前激活的 goal
/goal clear        # 清除它

机制细节（README 描述，源码常量见 backend/packages/harness/deerflow/runtime/goal.py）：

每次 Gateway 驱动的 run 结束后，用 non-thinking 评估模型把可见对话内容与激活 goal 比对；评估模型必须返回带类型的 blocker（missing_evidence、needs_user_input、run_failed、external_wait、goal_not_met_yet）并附可见证据；
仅在最近一轮 assistant 回复已被持久化 checkpoint、blocker 为 goal_not_met_yet、评估期间 thread 未变化、且无进展熔断器未触发时，才注入一次 hidden continuation；安全上限默认 8 次（即源码中的 DEFAULT_MAX_GOAL_CONTINUATIONS = 8），连续两次相同的无进展评估即停止；
/goal clear 与任何用户手动输入的新内容优先级高于排队的 continuation；goal 被满足时自动清除并发布更新后的 thread 状态。

Web UI 会在输入框上方展示当前激活 goal；同样命令在 TUI 与受支持 IM 渠道也可用。在 Web UI / IM 中，/goal <完成条件> 会以该条件启动一次 run，状态查询与清除命令只管理 goal 状态。

4.4 手动上下文压缩

在 Web UI 输入框输入 /compact，将当前 thread 的早期上下文压缩为摘要。完整聊天记录仍保留在界面上，但后续模型调用基于「压缩摘要 + 最近消息」继续；历史不足时不会压缩，thread 正在运行任务时会阻止压缩。系统级的自动压缩（含摘要生成、中间结果落盘、按 token/message/fraction 触发）见 config.example.yaml 的 summarization: 段。

4.5 Sub-Agents

Sub-agent 是执行优化，而不是遇到复杂任务的默认选择。 lead agent 只在委派有明确净收益时动态拉起 sub-agents，例如真正缩短耗时的并行、专业能力收益或上下文隔离收益：

存在跨 agent 依赖或重叠副作用的工作不会并行分派；当专业能力或上下文隔离收益明显占优时，一条有界顺序任务链仍可交给一个 sub-agent；
lead agent 使用能取得收益的最少 sub-agents，并在每批完成后重新评估，不因任务规模大就无限拆分；
每个 sub-agent 有独立上下文、工具与终止条件，返回结构化结果后由 lead agent 验证并汇总。

管理方式：管理员在 设置 → 子智能体 中添加/修改/停用/删除可复用工作智能体；内置项与 config.yaml 项以只读方式同目录展示。默认 Lead Agent 可用全部已启用的运行时 sub-agents；Custom Agent 可选择「全部 / 全禁 / 仅指定」，该范围同时约束模型可见目录与服务端 task 工具（不能靠直接填名称绕过）。设置页管理的数据是部署级全局数据，跟随 agent_storage.backend（单机原子文件，多实例共享数据库）。

相关运行时配置（config.example.yaml 中 subagent_runtime: 段）：

subagent_runtime:
  max_running: 3
  max_queued: 64
  admission_policy: queue       # queue 或 reject（槽位占满时）
  queue_timeout_seconds: 300

内置 sub-agent 有各自的超时与轮次上限（subagents.timeout_seconds 默认 1800 秒，bash 类默认更短；max_turns 内置 general-purpose=150、bash=60），可整体或按 agent 覆盖（subagents.agents.<name>.timeout_seconds/max_turns/model/skills/token_budget），也支持通过 subagents.custom_agents 定义带专属 system_prompt、工具白名单与技能白名单的自定义 sub-agent。当 max_concurrent_subagents 为 1 时，提示词会关闭并行与多批次路由指导，仅在有专业/隔离收益时保留委派。

4.6 Sandbox 与文件系统

「带工具的聊天机器人」与「真正有执行环境的 agent」的差别就在于：DeerFlow 真的给每个任务准备了一台「电脑」——隔离容器内拥有完整文件系统，agent 可以读写编辑文件、执行 bash 与代码、查看图片，全程可审计可隔离。

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

文件相关工具（ls/read_file/glob/grep/write_file/str_replace）由 backend/packages/harness/deerflow/sandbox 提供，上传侧另有应用级限制（config.example.yaml uploads: 段：默认 max_files: 10、max_file_size: 50 MiB、max_total_size: 100 MiB）。config.example.yaml 中还内置了 Read-Before-Write 文件门（read_before_write.enabled: true，防止长任务里盲目重复追加）与工具输出预算保护（tool_output 段：超过 externalize_min_chars 的输出落盘并以类型化摘要 + 文件引用替代，模型可经 read_file 回读完整内容）。

4.7 Agentic Browser Control

读取页面 ≠ 真正「使用」页面。除只读 web_fetch、web_capture 外，DeerFlow 提供一组可选 agentic browser 工具，为每对话保持一个实时浏览器会话，让 agent 导航、读取可交互元素、点击、输入、提交表单，并完成重度 JS 站点的多步流程。每次操作返回页面可交互元素最新快照，元素用稳定 [ref] 编号寻址（基于刚观察的内容行动，而非猜测选择器）；出站 URL 默认经 SSRF 筛查。

启用步骤：

cd backend
uv sync --extra browser
uv run playwright install chromium

然后在 config.yaml 取消注释 group: browser 工具项：browser_navigate、browser_snapshot、browser_click、browser_type、browser_get_text、browser_back、browser_screenshot、browser_close。注意事项：

make dev / Docker 启动检测到已启用 browser_navigate 时会在依赖同步时保留 browser extra；
配置了 browser control 但缺少 Playwright 时 Gateway 启动失败；/api/features 在后端无法提供该能力时隐藏 Browser UI；
除本地可信调试外保持 headless: true、allow_private_addresses: false；
通过 cdp_url 连已有 Chrome 时无法强制执行子资源/重定向 SSRF 防护，因此 fail closed，除非显式 allow_unguarded_cdp: true（仅限受信任本地浏览器）；
Browser session 是进程本地的，启用该组工具时保持 GATEWAY_WORKERS=1（普通 uvicorn worker 调度不提供 thread affinity）；
非 mock 的 Custom Agent 对话在 browser control 可用且 agent 未限制 tool_groups（或已含 browser 组）时，同样展示 Browser Live 控件。

workspace 的 Browser Live 客户端通过二进制 JPEG WebSocket 帧协商画面，每帧只保留最新待处理帧并回收被替换的 object URL；Gateway 控制消息仍为 JSON，未请求二进制能力的客户端继续用旧 JSON/base64 帧协议。

4.8 Context Engineering

隔离的 Sub-Agent Context：每个 sub-agent 在独立上下文中运行，看不到主 agent 与其他 sub-agents 的上下文，只聚焦当前任务。
摘要压缩：单 session 内较积极地管理上下文——总结已完成子任务、把中间结果转存文件系统、压缩暂时不重要的信息，在长链路多步骤任务中避免打爆上下文窗口。

4.9 长期记忆

DeerFlow 跨 session 逐步积累持久 memory（个人偏好、知识背景、长期工作习惯），memory 保存在本地、控制权始终在用户手中。默认后端为 DeerMem（manager_class: deermem，mode: middleware），采用「先分类、再确定性写入门」的被动抽取：判断候选信息的作用域、持久性与授权属性后，只把稳定、描述性的用户级事实写入长期记忆；当前对话约束与一次性授权留在对话状态。

关键可配置项（memory.backend_config: 段）及默认值包括：

max_facts: 100、fact_confidence_threshold: 0.7、debounce_seconds: 30、max_injection_tokens: 2000；
token_counting: tiktoken（网络受限环境可改 char，CJK-aware 且零网络 I/O）；
guaranteed_categories: [correction] + guaranteed_token_budget: 500：高价值修正（如「别用 pip 用 uv」）绕过常规预算保留注入；
容量淘汰：默认仅按 confidence 排序；显式 fact_eviction_policy: hybrid-v1 启用有界综合分 = confidence 65% + 用户确认新鲜度 25%（90 天半衰期）+ 查询召回热度 10%（30 天半衰期），并为 correction 保留 10%/最多 10 条最低槽位；fact_eviction_shadow_enabled: true 可在不改实际保留结果的情况下 shadow 对比两种策略；
陈旧性审查（staleness review）：staleness_age_days: 90 等参数控制周期式 KEEP/REMOVE/EXTEND 决策，复用已有 memory-update LLM 调用、不增加额外 API 开销；
memory.mode: tool 是独立的模型直写路径（memory_search/memory_add/memory_update/memory_delete）。

DeerMem 也支持 memory.backend_config.prompts_dir 覆盖内置抽取模板；若自定义模板未迁移新增的分类字段，写入门为 fail closed——所有抽取驱动的写入会停止，只能通过 rejected_by_scope_gate 指标与高拒绝率告警发现。除 DeerMem 外还支持 mem0、honcho、openviking、noop 等后端切换（manager_class 选择或点分路径）。

五、推荐模型

DeerFlow 对模型没有强绑定，理论上任何实现 OpenAI 兼容 API 的 LLM 都可接入；在以下能力上表现更强的模型更合适：

长上下文窗口（100k+ tokens），适合深度研究与多步骤任务；
推理能力，适合自适应规划与复杂拆解；
多模态输入，适合理解图片和视频；
稳定的 tool use 能力，适合可靠的函数调用与结构化输出。

官方 README 提到推荐使用 Doubao-Seed-2.0-Code、DeepSeek v3.2、Kimi 2.5 等模型运行 DeerFlow（火山引擎方舟提供 Coding Plan 多厂商网关）。config.example.yaml 中则收录了 volcengine(Doubao/GLM/DeepSeek/Kimi)、OpenAI（含 Responses API）、Claude、Gemini、Ollama、vLLM、MindIE、MiniMax、StepFun、Moonshot(Kimi)、Z.AI、OpenRouter、Novita、Atlas Cloud 等大量 provider 的完整配置样例与兼容性注解（含每个 provider 特有的 thinking 字段映射与回放要求）。

六、内嵌 Python Client

DeerFlow 也可作为内嵌 Python 库使用，不必启动完整 HTTP 服务。DeerFlowClient（源码见 backend/packages/harness/deerflow/client.py，导入路径 from deerflow.client import DeerFlowClient）提供进程内直接访问，覆盖所有 agent 与 Gateway 能力，返回数据结构与 HTTP Gateway API 保持一致：

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# Chat
response = client.chat("Analyze this paper for me", thread_id="my-thread")

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

# 配置与管理：返回值与 Gateway 对齐的 dict
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": [...]}
client.set_goal("thread-1", "finish the implementation and make all tests pass")
client.get_goal("thread-1")       # {"goal": {...}} or {"goal": None}
client.clear_goal("thread-1")

上例各方法在源码中均有对应实现（如 chat、stream、list_models、list_skills、update_skill、upload_files、set_goal/get_goal/clear_goal）。所有返回 dict 的方法会在 CI 中通过 Gateway 的 Pydantic 响应模型校验（TestGatewayConformance），确保内嵌 client 与 HTTP API schema 保持同步。此外 HTTP Gateway 还提供 DELETE /api/threads/{thread_id}，用于在 LangGraph thread 本身被删除后清理 DeerFlow 托管的本地 thread 数据。

七、定时任务（Scheduled Tasks）

DeerFlow 在 workspace 内置一等公民的定时任务 MVP，在 /workspace/scheduled-tasks 管理：

当前 MVP 能力：

每个任务可选复用同一 thread 及其历史对话，或每次运行新建 thread；
复制现有任务为可编辑草稿（不复制运行历史）；
支持 once 与 cron 两种调度；
后台执行以非交互式 run 运行（不暴露 ask_clarification）；
thread/全局配额忙时，到期执行持久化为 queued，可用后启动；队列项在 Gateway 重启后保留，超过 scheduler.queue_timeout_seconds 标记失败；
执行处于 queued/launching/running 时冻结任务定义；暂停/删除会取消已等待执行，launching/running 结束后才能重试变更；调度暂停时显式手动触发仍可执行且不自动恢复调度；
支持暂停、恢复、手动触发、查看历史、删除。

当前 MVP 限制： 暂无对话内创建任务的 schedule_task 工具、无纯文本通知、无渠道/GitHub 分发目标、第一版无 interval 调度。

启用配置（config.yaml -> scheduler）：

scheduler:
  enabled: false               # 开启后台轮询
  multi_instance: false        # 多 Pod 部署时设为 true
  poll_interval_seconds: 5
  lease_seconds: 120
  max_concurrent_runs: 3
  queue_timeout_seconds: 3600  # 队列等待超时后执行失败
  min_once_delay_seconds: 60
  recursion_limit: 1000        # 定时 run 的 LangGraph super-step 上限（与 Web UI 一致）

注意事项：

scheduler.recursion_limit 在 dispatch 时读取、下一次定时运行即生效（无需重启），超过 max_recursion_limit 的值会被截断；
后台调度器默认单实例。多 Pod 需 scheduler.multi_instance: true + 共享 Postgres + run_ownership.heartbeat_enabled: true + run_events.backend: db；max_concurrent_runs 是跨 Pod 共享全局上限，只计入 launching/running，queued 不占配额；
scheduler、ownership、run-event 相关字段只在启动时生效，修改后需协调重启所有 Gateway Pod。

升级说明（GATEWAY_WORKERS > 1 且 scheduler.enabled 时）：只在一个 worker 上启用调度器，或配置 multi_instance: true + 上述共享基础设施；升级后 Gateway 会在启动时拒绝不安全组合而非静默启动。max_concurrent_runs 是集群级上限，容量不会随副本数倍增。

八、终端工作台（TUI）

deerflow 是面向终端用户的工作台，内嵌运行在 DeerFlowClient 之上——无需 Gateway、前端、nginx 或 Docker，同时沿用同一套 config.yaml、checkpointer、技能、记忆、MCP 与沙箱配置。安装与使用：

uv pip install 'deerflow-harness[tui]'        # 可选的 'textual' 依赖

deerflow                                      # 启动终端 UI（需要 TTY）
deerflow --continue                           # 恢复最近一次会话
deerflow --resume THREAD                      # 按 id 恢复指定会话
deerflow --print "总结一下这个仓库"             # 无头模式，结果打印到 stdout
deerflow --json  "hello"                       # 无头模式，输出按行分隔的 StreamEvent

界面为键盘驱动：流式渲染的对话区（Markdown 渲染）、紧凑工具活动卡片、/ 斜杠命令面板、/model 与 /threads 选择器、输入历史，Esc/Ctrl+C 打断。在 TUI 里开启的会话也会出现在 Web UI 侧边栏——它以本地默认用户身份写入共享会话存储，终端与网页保持同步，无需运行 Gateway。完整说明见 backend/docs/TUI.md，源码位于 deerflow/tui/ 子包。

九、⚠️ 安全使用

DeerFlow 具备系统指令执行、资源操作、业务逻辑调用等高权限能力，默认设计为部署在本地可信环境（仅本机 127.0.0.1 回环访问）。

9.1 不当部署的安全风险

若部署到可被多终端访问的网络（不可信局域网、公网云服务器）且未加防护，可能导致：

未授权非法调用：agent 功能被第三方或公网恶意扫描程序探测并批量调用，进而执行系统命令、文件读写等高危操作；
合规与法律风险：agent 被非法调用实施网络攻击、信息窃取等违法违规行为时产生的责任。

9.2 Gateway 管理员权限等同于代码执行

管理员可注册 stdio 类型 MCP server，其命令会在 Gateway 容器内执行。API 将可执行命令限制在允许清单内（默认为 npx、uvx，可通过 DEER_FLOW_MCP_STDIO_COMMAND_ALLOWLIST 扩展），并拒绝会导致任意代码求值的参数与环境变量。这属于纵深防御而非安全边界——这类启动器本身就是拉取并运行远程包的工具，因此请将 Gateway 管理员权限视同宿主机上的代码执行，并据此谨慎授权。

9.3 部署默认值

Docker 部署栈默认只把入口端口发布到 127.0.0.1。需要从其他机器访问时，在 .env 中设置 BIND_HOST（如 BIND_HOST=0.0.0.0），且必须在落实下列安全措施之后再进行。请在主机变为可访问之前完成首次初始化设置：全新实例尚无账号，任何非仅回环访问的部署都应在启动后立即通过 /setup 创建管理员账号。

9.4 安全使用建议

建议将 DeerFlow 部署在本地可信网络；有跨设备/跨网络需求时加入严格措施：

设置访问 IP 白名单：使用 iptables 或硬件防火墙/带 ACL 的交换机，拒绝其他所有 IP 访问；
前置身份验证：配置反向代理（nginx 等）并开启高强度前置身份验证，禁止无认证访问；
网络隔离：尽可能把 agent 与可信设备划入同一专用 VLAN；
持续关注项目安全更新。

十、参与贡献、许可证与更多文档

DeerFlow 采用 MIT License 开源发布。开发环境、工作流与协作规范见 CONTRIBUTING.md；README 中注明回归测试已覆盖 Docker sandbox 模式识别以及 backend/tests 中 provisioner kubeconfig-path 相关测试。

常用仓库内文档索引：

文档	内容
backend/docs/CONFIGURATION.md	安装与配置说明（含 Sandbox 配置细节）
backend/docs/MCP_SERVER.md	MCP Server 扩展指南
backend/docs/IM_CHANNEL_CONNECTIONS.md	IM 渠道连接与安全设置
backend/docs/TUI.md	终端工作台完整说明
backend/CLAUDE.md	技术架构概览
backend/README.md	后端架构与 API 参考
skills/public/claude-to-deerflow/SKILL.md	claude-to-deerflow skill API
config.example.yaml	全量配置参考模板（当前 config_version 40）
Install.md	本地开发环境初始化

结语

DeerFlow 2.0 用「harness」思路重构了传统 agent framework：skills/tools 提供能力面，sandbox 提供真实执行环境，sub-agents 提供并行与隔离，memory 与 context engineering 维持长程任务的稳定性，IM 渠道、Gateway、TUI 与 Python client 则让它可以被嵌入任意工作流。你可以用 make setup 两分钟跑通、用 make up 长期服务化，也可以只内嵌 DeerFlowClient 或直接使用 TUI——这正是它「既能直接拿来用，也能拆开重组」的开放姿态。文中涉及的所有配置均可对照 config.example.yaml 的注释逐项验证，源码细节可在 backend harness 包的 models、sandbox、runtime、subagents、tui 等子模块中继续深入。

deer-flow

项目地址：https://gitcode.com/GitHub_Trending/de/deer-flow

登录后查看全文