DeerFlow 2.0 实战指南：从零配置、多模型接入到消息渠道与 Super Agent 架构解析

DeerFlow 2.0 是一个开源的 Super Agent Harness（代理运行时框架），它把 Sub-Agents（子代理）、长期记忆（Memory） 与 隔离 Sandbox 执行环境 组合在一起，由可扩展的 Skills（技能模块） 驱动，从而承接从数分钟到数小时不等的长程任务。本指南基于仓库根目录的 README_ru.md 整理，结合 config.example.yaml、Makefile 与 backend/ 源码展开：读完你可以独立完成环境搭建、模型/渠道/追踪配置，并理解「Deep Research → Super Agent Harness」这条产品与技术演化主线。

需要说明：原文档还包含外部官网、站外图表、推广活动等内容，这些与代码库无直接证据对应，本文一律不展开；其余技术内容均完整保留并辅以本仓库源码佐证。

一、DeerFlow 是什么：从 Deep Research 到 Super Agent Harness

DeerFlow 全称 Deep Exploration and Efficient Research Flow。根据 README_ru.md 的表述，项目最初定位为 Deep Research（深度研究）框架，但在社区使用中被扩展出报告/幻灯片生成、仪表盘搭建、内容自动化等超出研究范畴的用法。开发者据此意识到它不应只是「研究工具」，而是一个给 Agent 提供基础设施的 harness（运行时），于是整个项目被从零重写为 DeerFlow 2.0。

几个判断当前仓库版本的硬性依据：

• Python 要求 3.12+，Node.js 要求 22+，对应 backend/pyproject.toml 与根 Makefile；
• 技术底座是 LangGraph 与 LangChain（多代理编排图 + LLM 交互链）；
• 2.0 与 1.x 无共享代码，1.x 深度研究版本不再继续维护，活跃开发集中在 2.0；
• 默认「开箱即用」（batteries included）：文件系统、memory、skills、sandbox 执行、sub-agents 规划与并行执行都已内置，且支持「直接用」或「拆开按需重组」两种使用方式。

从代码结构看，这一论断有直接映射：仓库根目录下 skills/public 存放内置公开技能，backend/app/gateway/ 是 HTTP 网关层，backend/packages/harness/ 是核心 harness 包，三者共同构成「Lead Agent + Sub-Agents + Sandbox」的运行骨架。

二、快速上手：给 Coding Agent 的一句话指令

若你使用 Claude Code、Codex、Cursor、Windsurf 等 coding agent，原文档建议直接发送如下 prompt（为符合本仓库安装说明，将外部 raw URL 替换为仓库内 Install.md）：

如果 DeerFlow 尚未克隆，请先克隆它，然后按照仓库中的 Install.md 说明准备本地开发环境。

该 prompt 让 agent 在必要时先克隆仓库，有 Docker 时优先选择 Docker，并在最后返回精确的启动命令与缺失配置清单。

三、快速开始：配置与启动

3.1 克隆与自动配置向导

1. 克隆仓库：

   git clone https://gitcode.com/GitHub_Trending/de/deer-flow.git
   cd deer-flow
   

2. 启动配置向导（推荐）：

   make setup
   

   make setup 实际调用的是 scripts/setup_wizard.py。它是一个交互式向导，会引导你选择 LLM 提供商、可选 Web 搜索、执行/安全设置（sandbox 模式、bash 访问权限、文件写入工具），最终生成最小可用的 config.yaml，并把密钥写入项目根的 .env，全程约 2 分钟。

3. 随时体检与排障：

   • make doctor：调用 scripts/doctor.py，检查配置并给出具体修复提示；
   • make support-bundle：调用 scripts/support_bundle.py（带 --include-doctor），用于准备 issue 材料。它会生成 *-issue-summary.md（可直接贴入 issue）、*-issue-draft.md（供 AI 起草 issue，必须替换所有 REQUIRED 占位符而非编造事实），并可选择在 .deer-flow/support-bundles/ 下生成诊断 zip。诊断包只包含脱敏后的诊断信息与文件清单，不会包含 .env、对话原文或用户文件内容；zip 仅在维护者索要时附上。

4. 高级/手动配置：若想直接编辑 config.yaml，改执行 make config（对应 scripts/configure.py）以复制完整模板。完整的参数参考以根目录 config.example.yaml 为准，其中覆盖了 CLI 提供商（Codex CLI、Claude Code OAuth）、OpenRouter、Responses API 等进阶用法。

3.2 手动模型配置示例

原文档给出的手动配置模型片段（也是 config.example.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

要点解释：

• OpenAI 兼容网关（OpenRouter 等）：使用 langchain_openai:ChatOpenAI 并显式指定 base_url；若想使用与提供商同名的环境变量，可在 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 这类 reasoning 模型，DeerFlow 通过 extra_body.chat_template_kwargs.enable_thinking 切换推理模式，并在多轮工具调用中保留 vLLM 的非标准 reasoning 字段；旧式 thinking 配置会自动归一化以保持向后兼容。reasoning 模型可能需要服务端以 --reasoning-parser ... 启动；若本地 vLLM 接受任意非空 API key，也应把 VLLM_API_KEY 设为占位值。

CLI 型提供商示例（读本机 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)"
  

  该脚本源码位于 scripts/export_claude_code_oauth.py。

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

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

补充仓库佐证：根目录 config.example.yaml 的 models: 段（约从 L131 起）给出了更多真实生产示例——如火山方舟 Doubao 模型（deerflow.models.patched_deepseek:PatchedChatDeepSeek + api_base）、Coding Plan 多厂商网关 /api/coding/v3、必需 thinking 模型变体等，并支持为每个模型声明 context_window、supports_vision、supports_reasoning_effort、timeout、max_retries、pricing（每百万 token 计费，多模型须统一币种）等元信息。

3.3 启动：Docker（推荐）与本地开发两种方式

方案 A：Docker

# 开发模式（hot-reload、挂载源码）
make docker-init    # 拉取 Sandbox 镜像（一次性，或在镜像更新后执行）
make docker-start   # 启动服务

# 生产模式（本地构建镜像）
make up     # 构建镜像并启动全部服务
make down   # 停止并移除容器

对照根 Makefile：docker-init/docker-start 内部调用 scripts/docker.sh 的 init/start，up/down 调用 scripts/deploy.sh。若在 Linux 上遇到 Docker daemon permission denied，请把当前用户加入 docker 组后重新登录（详见 CONTRIBUTING.md）。服务地址：http://localhost:2026。

方案 B：本地开发

前置条件：先完成 3.1 的 make setup（make dev 需要根目录存在有效 config.yaml）。

环境变量约定：

• DEER_FLOW_PROJECT_ROOT：显式指定项目根目录；
• DEER_FLOW_CONFIG_PATH：指定具体配置文件路径（backend/README.md 亦记录了该变量）；
• DEER_FLOW_HOME：运行时状态默认写到项目根的 .deer-flow，可用此变量迁移；
• DEER_FLOW_SKILLS_PATH：skills 默认从项目根 skills/ 读取，可覆盖路径。

Windows 用户需在 Git Bash 中运行本地开发进程；cmd.exe 与 PowerShell 不支持这些 bash 服务脚本，WSL 也不保证可用（部分脚本依赖 Git for Windows 的 cygpath 等工具）。

make check          # 校验 Node.js 22+、pnpm、uv、nginx
make install        # 安装后端(uv sync --locked)与前端(pnpm install)依赖
make setup-sandbox  # （可选）提前拉取 Sandbox 镜像
make dev            # 启动服务（hot-reload）

启动成功后同样访问 http://localhost:2026。make dev 对应 scripts/serve.sh 的 --dev 模式，make check 对应 scripts/check.py。

四、Sandbox 执行模式与容器文件系统

DeerFlow 支持多种执行模式（原文档原文）：

• 本地执行（Local）——代码直接在宿主机运行；
• Docker——在隔离 Docker 容器中执行；
• Docker + Kubernetes——通过 provisioner 在 Kubernetes Pod 中执行。

完整配置见 backend/docs/CONFIGURATION.md 的 Sandbox 章节。

从 config.example.yaml 的 sandbox: 段（约 L1327 起）可以看到默认实现与安全默认值：

sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
  # 宿主机 bash 默认关闭：LocalSandboxProvider 不是 shell 访问的安全隔离边界
  allow_host_bash: false
  # 可选：把宿主机目录挂载进 sandbox
  # mounts:
  #   - host_path: /home/user/my-project
  #     container_path: /mnt/my-project
  #     read_only: true
  # 工具输出截断阈值（字符）
  bash_output_max_chars: 20000
  read_file_output_max_chars: 50000
  ls_output_max_chars: 20000
  # 单条宿主 bash 命令最长墙钟时间（秒），超时杀死整条进程组
  bash_command_timeout: 600

需要注意：

• allow_host_bash 只在「完全可信的单用户本地工作流」下开启，因为 LocalSandboxProvider 不是安全隔离边界；
• 注释掉的部分给出了容器型 AIO Sandbox 的切换方式（deerflow.community.aio_sandbox:AioSandboxProvider），macOS 上优先 Apple Container、其余平台使用 Docker；
• 截断策略有讲究：bash 输出用「中段截断」（保留头尾），read_file/ls 用「头截断」；设为 0 可关闭截断；
• bash_command_timeout 防止前台阻塞命令（如未后台化的服务器）拖死整个回合，长驻进程应重定向输出到后台运行。

Sandbox 内的目录布局（原文档给出）：

# 容器内 sandbox 路径
/mnt/user-data/
├── uploads/          ← 你上传的文件
├── workspace/        ← 代理的工作目录
└── outputs/          ← 产出结果

技能挂载路径：

# 容器内路径
/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/public 一一对应——实际仓库内置了 deep-research/、data-analysis/、image-generation/、ppt-generation/、video-generation/、frontend-design/ 等二十余个技能目录，每个技能即一个含 SKILL.md 的模块。

五、扩展能力：MCP 服务器与消息渠道

5.1 MCP 服务器

DeerFlow 支持可自定义的 MCP 服务器来扩展能力；对 HTTP/SSE MCP 服务器支持 OAuth token（client_credentials、refresh_token）。详见 backend/docs/MCP_SERVER.md。

5.2 从 IM 渠道收发任务

DeerFlow 能直接从消息应用接收任务，渠道在配置后自动启动、无需公网 IP。此外，启用 channel_connections 后，登录用户在 workspace UI（侧边栏 / Settings > Channels）可自行绑定 Telegram、Slack、Discord、飞书/Lark、钉钉、微信或企微——该功能复用现有 channels.* 出站传输，因此也不需要公网 IP 或回调 URL。入站 IM 消息以所绑定 DeerFlow 用户身份执行。细节与安全说明见 backend/docs/IM_CHANNEL_CONNECTIONS.md。

渠道一览（复杂度为原文档评估）：

渠道	传输方式	复杂度
Telegram	Bot API（long-polling）	简单
Slack	Socket Mode	中等
Feishu / Lark	WebSocket	中等
WeChat	Tencent iLink（long-polling）	中等
WeCom	WebSocket	中等
DingTalk	Stream Push（WebSocket）	中等

config.yaml 中的渠道配置示例（完整保留原文）：

channels:
  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
    app_token: $SLACK_APP_TOKEN
    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

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

.env 中的密钥：

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

# DingTalk
DINGTALK_CLIENT_ID=your_client_id
DINGTALK_CLIENT_SECRET=your_client_secret

各渠道的注册/配置步骤（完整继承原文，可直接照做）：

• Telegram：向 @BotFather 发送 /newbot 获取 HTTP API token → 把 TELEGRAM_BOT_TOKEN 写入 .env 并在 config.yaml 启用 channels.telegram。
• WeChat：在 config.yaml 启用 wechat；二选一设置 WECHAT_BOT_TOKEN 或开启 qrcode_login_enabled: true。无 bot_token 且开启二维码时，关注后端日志中 iLink 返回的二维码内容完成绑定；成功后 DeerFlow 会把获得的 token 存入 state_dir，供重启复用。Docker Compose 部署时请把 state_dir 放在持久卷上，以保住 get_updates_buf 游标与认证状态。
• WeCom（企微）：在 WeCom AI Bot 平台创建机器人并取得 bot_id/bot_secret → 写入 config.yaml 与 .env → 确认后端依赖包含 wecom-aibot-python-sdk。渠道使用长连接 WebSocket，无需回调 URL；目前支持收发文本、图片与文件，agent 产出的图片/文件也可回发到会话。
• DingTalk：在钉钉开放平台创建应用并开启「机器人」能力 → 机器人消息接收模式选 Stream → 复制 Client ID/Secret 写入 .env 并启用渠道 → （可选）在卡片平台创建 AI Card 模板实现打字机流式回复，把模板 ID 填入 card_template_id，同时申请 Card.Streaming.Write 与 Card.Instance.Write 权限。

通用聊天命令（所有渠道一致）：

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

不带命令的消息视为普通聊天——DeerFlow 会创建 thread 并回复。

六、可观测性：LangSmith / Langfuse 追踪

6.1 LangSmith

在项目根 .env 中加入：

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
LANGSMITH_PROJECT=deer-flow

• LANGSMITH_ENDPOINT 默认 https://api.smith.langchain.com，可按需覆盖；
• 旧式 LANGCHAIN_* 变量（LANGCHAIN_TRACING_V2、LANGCHAIN_API_KEY 等）仍受支持以向后兼容；两者同时设置时 LANGSMITH_* 优先。

6.2 Langfuse

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 换成你的部署地址。

轨迹关联字段（每次 agent 运行都会用 Langfuse 保留属性标注，Sessions/Users 页面自动填充）：

• session_id = LangGraph 的 thread_id——同一对话的所有轨迹归组；
• 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 是否打印进日志）。

这些字段在图调用根部的 RunnableConfig.metadata 中被注入，无论是 gateway 路径（backend/packages/harness/deerflow/runtime/runs/worker.py 中的 run_agent）还是内置客户端路径（client.py 的 DeerFlowClient.stream），任何 LangChain 兼容 callback 都能读到。可设置 DEER_FLOW_ENV（或 ENVIRONMENT）以按部署环境打标签。

6.3 双追踪与失败策略

• 同时启用 LangSmith 与 Langfuse 时，DeerFlow 会挂载两个 callback 并把同一份模型活动发给两套系统；
• 若某 provider 显式启用但缺凭证、或其 callback 无法初始化，DeerFlow 会在建模型阶段 fail fast 终止，并在报错中指明出问题的 provider；
• Docker 部署默认关闭追踪，需要在 .env 中显式设置 LANGSMITH_TRACING=true 与 LANGSMITH_API_KEY 开启。

七、核心特性解读

7.1 Skills & Tools

Agent Skill 是一个结构化模块：一份描述工作流、最佳实践与资源引用链接的 SKILL.md。DeerFlow 内置了研究、报告生成、幻灯片、网页、图像与视频等技能；真正的价值在可扩展性——可以新增自己的技能、替换内置技能，或把多个技能组合成复合工作流（如上文 skills/public 目录所见，实际内置技能远多于文档示例）。

关键设计：按需懒加载——只有任务真正需要某技能时才加载，从而保持上下文窗口「干净」。这与 config.example.yaml 中技能启用开关、以及 backend/docs/CONFIGURATION.md 的技能配置相互印证。

Claude Code 集成：claude-to-deerflow 技能让你直接在 Claude Code 终端里驱动 DeerFlow，无需离开命令行。安装方式：

npx skills add <deer-flow 仓库地址> --skill claude-to-deerflow

（安装命令中 skills 为第三方 CLI；本仓库内技能的完整 API 参考见 skills/public/claude-to-deerflow/SKILL.md。）

可用能力：

• 向 DeerFlow 发消息并接收流式回复；
• 选择执行模式：flash（快）、standard、pro（planning）、ultra（sub-agents）；
• 查看 DeerFlow 状态、模型、技能、代理；
• 管理 thread 与对话历史；
• 上传文件用于分析。

7.2 会话目标（Session Goals）

用 /goal <完成条件> 为当前 thread 绑定一个生效的完成条件。目标是 thread 级状态（而非某次技能触发），因此会在多轮之间持续生效，直到 DeerFlow 判定其完成或你手动清除：

/goal finish the implementation and make all tests pass
/goal              # 查看当前生效目标
/goal clear        # 清除目标

工作机制（原文档详述）：

• 每个经 Gateway 执行完成的 run 结束后，DeerFlow 用非 thinking 的评估模型对照目标评估可见对话；评估器必须返回带可见证据的类型化 blocker，类型为 missing_evidence、needs_user_input、run_failed、external_wait 或 goal_not_met_yet 之一；
• 仅当满足全部条件时才追加 hidden continuation：最后一条 assistant 轮次已保存进 checkpoint、blocker 类型为 goal_not_met_yet、评估期间 thread 未变化、且「无进展计数」未触发；
• 默认安全上限为 8 次 hidden continuation；重复出现同结果且无进展时，2 次后停止；
• /goal clear 或用户任何新输入，优先级高于排队中的 continuation；
• 目标达成后 DeerFlow 自动清除并发布更新后的 thread 状态。

UI 呈现：Web 界面在输入框上方显示活动目标；TUI 与受支持的 IM 渠道也支持该命令。在 Web 与受支持 IM 渠道中，/goal <条件> 会顺带启动一次把条件当作任务的执行，而状态/清除类命令只管理目标状态。仓库内对应实现与测试可见于 backend/tests/test_goal_runtime.py、backend/tests/test_goal_worker.py。

7.3 Sub-Agents（子代理）

复杂任务很少一次完成，DeerFlow 负责分解：

• Lead agent 按需即时拉起 sub-agents，每个都拥有独立的上下文、工具集与完成条件；
• Sub-agents 并行工作、返回结构化结果，由 lead agent 汇总为最终产出；
• 这正是 DeerFlow 承接「数分钟到数小时」任务的方式——研究任务可分叉为十几个 sub-agent 各自深挖，再汇聚成一份报告、一个网站或一套含可视化素材的幻灯片：「一个 harness，多双手」。

7.4 Sandbox 与文件系统（“它有自己的电脑”）

DeerFlow 不只是宣称能做事，而是真正拥有隔离执行环境。每个任务跑在独立 Docker 容器内，拥有完整文件系统（skills、workspace、uploads、outputs）。Agent 能读写/编辑文件、执行 bash、写代码、看图，全部隔离且透明，会话之间零串扰。用原文档的原话说：这是「带工具的聊天机器人」与「拥有真实执行环境的 Agent」之间的差别。

7.5 上下文工程（Context Engineering）

• 隔离上下文：每个 sub-agent 只见自己的上下文，看不到 lead agent 或其他 sub-agent 的上下文，从而聚焦自身任务；
• 上下文管理：会话内 DeerFlow 会激进地压缩上下文——对已完成的子任务做摘要、把中间结果卸载到文件系统、压缩不再相关的历史，使长程多步任务不撑爆上下文窗口。

7.6 长期记忆（Long-Term Memory）

多数 Agent 在对话结束后就「失忆」，而 DeerFlow 会跨会话保存用户画像、偏好与累积知识。用得越多，它越了解你的写作风格、技术栈与重复工作流。所有数据本地存储、用户可控。

八、推荐模型特征

DeerFlow 通过 OpenAI 兼容 API 兼容任意 LLM，最适合具备以下能力的模型：

• 大上下文窗口（100k+ tokens）——支撑 deep research 与多步任务；
• Reasoning 能力——支撑自适应规划与复杂任务分解；
• 多模态输入——处理图片、视频；
• 强工具调用——稳定的 function calling 与结构化输出。

九、内置 Python 客户端（无需起 HTTP 服务）

DeerFlow 可被当作 Python 库直接嵌入代码，无需运行 HTTP 服务。backend/packages/harness/deerflow/client.py 中的 DeerFlowClient 暴露了全部 agent/Gateway 能力，且返回与 HTTP Gateway API 一致的响应 schema（即 {"models": [...]} 这类 Gateway 对齐的 dict）。HTTP Gateway 还额外提供 DELETE /api/threads/{thread_id}，用于在 LangGraph thread 本身被删除后，清理由 DeerFlow 管理的本地 thread 数据。

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

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

# 流式（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")

从源码看，上述方法在 client.py 中都有直接实现（如 chat、stream、list_models、list_skills、update_skill、upload_files、get_goal/set_goal/clear_goal）；SSE 事件流契约可参见 backend/docs/RUN_EVENT_STREAM.md。

十、定时任务（Scheduled Tasks）

workspace 中内置了一等公民的 scheduled-task MVP，管理入口在 /workspace/scheduled-tasks。当前能力（原文完整列出）：

• 每个定时任务可选「复用同一 thread」或「每次运行新建 thread」；
• 支持 once 与 cron 两种调度；
• 后台定时 run 以非交互方式执行（不提供 ask_clarification）；
• 当某个 cron run 到期与同一复用 thread 上的活动 run 撞车时，采用 skip 重叠策略；
• 支持暂停、恢复、手动触发、查看历史、删除任务；
• 定时任务走标准 DeerFlow run 生命周期。

当前 MVP 限制：

• 暂无在对话中创建任务的 schedule_task 工具；
• 暂无带文本通知的任务；
• 暂无 GitHub 渠道/投递目标；
• 首版不含 interval 调度类型。

开启方式：config.yaml 中设 scheduler.enabled。与之对应的默认参数见 config.example.yaml 的 scheduler: 段（约 L2316 起）：

scheduler:
  enabled: false
  multi_instance: false       # 是否在多个 Gateway 实例间开启租约感知恢复
  poll_interval_seconds: 5
  lease_seconds: 120
  max_concurrent_runs: 3
  queue_timeout_seconds: 3600
  min_once_delay_seconds: 60
  recursion_limit: 1000

multi_instance、lease_seconds 等字段对应的是跨实例抢单与崩溃恢复语义；相关测试覆盖可参考 backend/tests/test_scheduled_task_* 系列。

十一、终端面板（TUI）

deerflow 是面向终端用户的原生 TUI。它内嵌运行在 DeerFlowClient 之上——无需 Gateway、前端、nginx 或 Docker——同时尊重与其余 DeerFlow 相同的 config.yaml 设置、checkpointer、skills、memory、MCP 与 sandbox。

安装与运行：

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

deerflow                                      # 启动终端 UI（需要 TTY）
deerflow --continue                           # 恢复最近一个 thread
deerflow --resume THREAD                      # 按 id 恢复指定 thread
deerflow --print "summarize this repo"        # 单次独立回答，输出到 stdout
deerflow --json  "hello"                       # 独立模式，按行输出 StreamEvents

功能特性：全键盘操作聊天界面，流式转写（Markdown 渲染）、紧凑的工具活动卡片、/ 斜杠命令面板、/goal 目标管理、/model 与 /threads 选择器、输入历史、Esc/Ctrl+C 中断。TUI 中打开的会话也会出现在 Web 界面侧边栏——因为 TUI 默认以本地用户身份写入同一 thread 存储，因此无需启动 Gateway，终端与 Web 也能保持同步。完整指南见 backend/docs/TUI.md。

十二、配套文档导航

• CONTRIBUTING.md——开发环境搭建、工作流与规范；
• backend/docs/CONFIGURATION.md——配置说明；
• backend/docs/IM_CHANNEL_CONNECTIONS.md——IM 渠道连接细节；
• backend/docs/MCP_SERVER.md——MCP 服务器扩展；
• backend/docs/TUI.md——TUI 完整手册；
• 架构总览：backend/README.md（含后端与 API 参考）与 backend/CLAUDE.md（技术细节，亦有中译 backend/README_zh.md）。

十三、⚠️ 安全部署须知

13.1 错误部署的威胁

DeerFlow 具备高特权能力：系统命令执行、资源操作与业务逻辑调用。默认设计面向本地可信环境（仅 loopback 127.0.0.1 可访问）。若在非可信环境（局域网、公网云服务器、多设备可达的环境）部署而未加严格防护，可能面临：

• 未授权调用：agent 功能被第三方/恶意扫描器发现，造成大量以高风险操作（系统命令、文件读写）为载体的未授权请求，后果严重；
• 法律与合规风险：若被用于网络攻击、数据窃取等非法行为，将带来法律责任与合规风险。

13.2 安全建议

官方强烈建议仅在本地可信网络部署。若确需多设备/跨网络部署，务必落实：

• IP 白名单：使用 iptables 或带 ACL 的硬件防火墙/交换机配置 IP 白名单，阻断其余全部地址；
• 认证网关：配置反向代理（如 nginx）并开启严格前置认证，拒绝一切未授权访问；
• 网络隔离：尽可能把 agent 与可信设备放入独立 VLAN，与其余网络隔离；
• 关注更新：定期跟踪 DeerFlow 项目的安全更新。

仓库中 backend/app/gateway/auth_disabled.py 等文件也表明：DEER_FLOW_ENV/ENVIRONMENT 环境变量会在本地/E2E 场景下参与认证模式的判定，生产部署前务必确认认证与授权已按 backend/docs/AUTH_DESIGN.md 等文档正确开启。

十四、开源协议与致谢

项目以 MIT 许可证 发布，见仓库根目录 LICENSE。DeerFlow 的技术底座是 LangChain（LLM 交互与链式构建）与 LangGraph（支撑复杂多代理工作流编排的图运行时），相关依赖声明在 backend/pyproject.toml。贡献者可通过 CONTRIBUTING.md 了解环境搭建与提交流程。

---

小结：从本文可以看出，DeerFlow 2.0 的核心不是某一个模型或工具，而是一整套可组合的运行时：Skills 定义「会什么」，Sandbox 提供「能做什么」的物理环境，Session Goals 约束「做到什么程度算完」，Sub-Agents 与 Context Engineering 解决「长任务怎么并行与不丢上下文」，Long-Term Memory 解决「跨会话记住什么」，而 Gateway、Python 客户端与 TUI 则分别覆盖 HTTP、代码内嵌与终端三种使用形态。上手最快的路径仍是 make setup → make docker-start（或 make dev）→ 打开 http://localhost:2026，再按需接入消息渠道与追踪系统。