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

2026 年 2 月 28 日，DeerFlow 在 v2 发布后登顶 GitHub Trending 🏆 第一！万分感谢我们了不起的社区 —— 是你们让这一切发生！💪🔥

DeerFlow（D eep E xploration and E fficient R esearch Flow）是一个开源的超级智能体框架，通过可扩展的技能协调子智能体、记忆和沙箱来执行几乎任何任务。

视频/嵌入内容：DeerFlow 演示

注意

DeerFlow 2.0 是从头重写的版本，与 v1 不共享任何代码。如果您需要原始的 Deep Research 框架，它维护在 1.x 分支上 —— 仍然欢迎贡献。活跃开发已移至 2.0。

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

来自字节跳动火山引擎的编码计划

DeerFlow 最近集成了 BytePlus 独立开发的智能搜索与爬取工具集 —— InfoQuest（支持免费在线体验）

---

如果您使用 Claude Code、Codex、Cursor、Windsurf 或其他编程智能体，可以用一句话将设置说明交给它：

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

该提示面向编程智能体。它会指示智能体在必要时克隆仓库，优先使用 Docker，并停在确切的下一步命令以及用户仍需提供的缺失配置。

1. 克隆 DeerFlow 仓库

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

2. 运行设置向导

在项目根目录 (deer-flow/) 下运行：

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

向导还会让您配置可选的网络搜索提供商，或暂时跳过。

随时运行 make doctor 来验证您的设置并获得可操作的修复提示。如果您正在提交关于本地设置或运行时问题的 GitHub issue，请运行 make support-bundle。该命令会打印报告后续步骤，写入一个用于粘贴到 issue 的 *-issue-summary.md 文件、一个用于 AI 辅助提交 issue 的 *-issue-draft.md 文件，以及一个可选的证据 zip 包，路径为 .deer-flow/support-bundles/。如果由 AI 助手提交 issue，请从草稿开始，并替换所有 REQUIRED 占位符，而不是编造缺失的事实。仅当维护者要求，或仅凭摘要不够时，才附加 zip 包。维护者和 AI 分类工具可以从 triage.json 开始；该包仅包含经过脱敏的诊断信息和文件清单，不包含 .env、原始对话消息或用户文件内容。

高级/手动配置：如果您更喜欢直接编辑 config.yaml，请改为运行 make config 复制完整模板。有关完整参考，包括 CLI 支持的提供商（Codex CLI、Claude Code OAuth）、OpenRouter、Responses API 等，请参见 config.example.yaml。

手动模型配置示例

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 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	推荐用于共享使用、多智能体运行、报告生成或更重的沙箱工作负载。

• 以上数字仅涵盖 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

对于持久化部署，请将 database.backend 配置为 sqlite 或 postgres。所选后端由 LangGraph 检查点、LangGraph Store 和 DeerFlow 应用数据共享。已弃用的 checkpointer 部分（如果存在）会覆盖前两者以实现向后兼容。

统一的 nginx 端点默认同源，且不会发送浏览器 CORS 头。如果您运行跨源或端口转发的浏览器客户端，请将 GATEWAY_CORS_ORIGINS 设置为以逗号分隔的精确来源，例如 http://localhost:3000；网关随后会应用 CORS 允许列表和匹配的 CSRF 来源检查。

重要

网关仍在进程中持有活动运行任务，因此生产环境默认使用单个网关工作进程（GATEWAY_WORKERS=1）。Redis 流桥接（stream_bridge.type: redis）在工作进程间共享 SSE 推送和 Last-Event-ID 重播，并使用滚动保留缓冲区 TTL（stream_ttl_seconds）作为清理安全网。它本身不会使运行取消、请求去重或 IM 通道状态完全跨工作进程；在增加 GATEWAY_WORKERS 之前，请使用单工作进程网关或明确的粘性路由/所有权。

有关详细的 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 中运行本地开发流程。原生的 cmd.exe 和 PowerShell 终端不支持基于 bash 的服务脚本，且不保证 WSL 可用，因为部分脚本依赖于 Git for Windows 的 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

这会将示例夹具复制到默认的本地运行时记忆文件中，以便审查者可以立即测试 Settings > Memory。

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

On February 28th, 2026, DeerFlow claimed the 🏆 #1 spot on GitHub Trending following the launch of version 2. Thanks a million to our incredible community — you made this happen! 💪🔥

DeerFlow (D eep E xploration and E fficient R esearch Flow) is an open-source super agent harness that orchestrates sub-agents , memory , and sandboxes to do almost anything — powered by extensible skills.

deer-flow-720p.mp4

Note

DeerFlow 2.0 is a ground-up rewrite. It shares no code with v1. If you're looking for the original Deep Research framework, it's maintained on the 1.x branch — contributions there are still welcome. Active development has moved to 2.0.

Learn more and see real demos on our official website.

Coding Plan from ByteDance Volcengine

DeerFlow has newly integrated the intelligent search and crawling toolset independently developed by BytePlus--InfoQuest (supports free online experience)

---

If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can hand it the setup instructions in one sentence:

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

That prompt is intended for coding agents. It tells the agent to clone the repo if needed, choose Docker when available, and stop with the exact next command plus any missing config the user still needs to provide.

1. Clone the DeerFlow repository

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

2. Run the setup wizard

From the project root directory (deer-flow/), run:

This launches an interactive wizard that guides you through choosing an LLM provider, optional web search, and execution/safety preferences such as sandbox mode, bash access, and file-write tools. It generates a minimal config.yaml and writes your keys to .env. Takes about 2 minutes.

The wizard also lets you configure an optional web search provider, or skip it for now.

Run make doctor at any time to verify your setup and get actionable fix hints. If you are opening a GitHub issue about a local setup or runtime problem, run make support-bundle. The command prints reporter next steps, writes a *-issue-summary.md file to paste into the issue, a *-issue-draft.md file for AI-assisted issue filing, and an optional evidence zip under .deer-flow/support-bundles/. If an AI assistant files the issue, start from the draft and replace every REQUIRED placeholder instead of inventing missing facts. Attach the zip only if a maintainer asks for it, or if the summary alone is not enough. Maintainers and AI triage tools can start with triage.json; the bundle includes redacted diagnostics and file manifests only, and does not include .env, raw conversation messages, or user file contents.

Advanced / manual configuration : If you prefer to edit config.yaml directly, run make config instead to copy the full template. See config.example.yaml for the complete reference including CLI-backed providers (Codex CLI, Claude Code OAuth), OpenRouter, Responses API, and more.

Manual model configuration examples

     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 and similar OpenAI-compatible gateways should be configured with langchain_openai:ChatOpenAI plus base_url. If you prefer a provider-specific environment variable name, point api_key at that variable explicitly (for example api_key: $OPENROUTER_API_KEY).

To route OpenAI models through /v1/responses, keep using langchain_openai:ChatOpenAI and set use_responses_api: true with output_version: responses/v1.

For vLLM 0.19.0, use deerflow.models.vllm_provider:VllmChatModel. For Qwen-style reasoning models, DeerFlow toggles reasoning with extra_body.chat_template_kwargs.enable_thinking and preserves vLLM's non-standard reasoning field across multi-turn tool-call conversations. Legacy thinking configs are normalized automatically for backward compatibility. Reasoning models may also require the server to be started with --reasoning-parser .... If your local vLLM deployment accepts any non-empty API key, you can still set VLLM_API_KEY to a placeholder value.

CLI-backed provider examples:

     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 reads `~/.codex/auth.json`
 * Claude Code accepts `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_CREDENTIALS_PATH`, or `~/.claude/.credentials.json`
 * ACP agent entries are separate from model providers — if you configure `acp_agents.codex`, point it at a Codex ACP adapter such as `npx -y @zed-industries/codex-acp`
 * On macOS, export Claude Code auth explicitly if needed:

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

API keys can also be set manually in .env (recommended) or exported in your shell:

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

Use the table below as a practical starting point when choosing how to run DeerFlow:

Deployment target	Starting point	Recommended	Notes
Local evaluation / make dev	4 vCPU, 8 GB RAM, 20 GB free SSD	8 vCPU, 16 GB RAM	Good for one developer or one light session with hosted model APIs. 2 vCPU / 4 GB is usually not enough.
Docker development / make docker-start	4 vCPU, 8 GB RAM, 25 GB free SSD	8 vCPU, 16 GB RAM	Image builds, bind mounts, and sandbox containers need more headroom than pure local dev.
Long-running server / make up	8 vCPU, 16 GB RAM, 40 GB free SSD	16 vCPU, 32 GB RAM	Preferred for shared use, multi-agent runs, report generation, or heavier sandbox workloads.

• These numbers cover DeerFlow itself. If you also host a local LLM, size that service separately.
• Linux plus Docker is the recommended deployment target for a persistent server. macOS and Windows are best treated as development or evaluation environments.
• If CPU or memory usage stays pinned, reduce concurrent runs first, then move to the next sizing tier.

Option 1: Docker (Recommended)

Development (hot-reload, source mounts):

make docker-init    # Pull sandbox image (only once or when image updates)
make docker-start   # Start services (auto-detects sandbox mode from config.yaml)

make docker-start starts provisioner only when config.yaml uses provisioner mode (sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider with provisioner_url).

Docker builds use the upstream uv registry by default. If you need faster mirrors in restricted networks, export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple and NPM_REGISTRY=https://registry.npmmirror.com before running make docker-init or make docker-start.

Backend processes automatically pick up config.yaml changes on the next config access, so model metadata updates do not require a manual restart during development.

Tip

On Linux, if Docker-based commands fail with permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, add your user to the docker group and re-login before retrying. See CONTRIBUTING.md for the full fix.

Production (builds images locally, mounts runtime config and data):

make up     # Build images and start all production services
make down   # Stop and remove containers

Access: http://localhost:2026

For persistent deployments, configure database.backend as sqlite or postgres. The selected backend is shared by the LangGraph checkpointer, LangGraph Store, and DeerFlow application data. The deprecated checkpointer section, when present, overrides the first two for backward compatibility.

The unified nginx endpoint is same-origin by default and does not emit browser CORS headers. If you run a split-origin or port-forwarded browser client, set GATEWAY_CORS_ORIGINS to comma-separated exact origins such as http://localhost:3000; the Gateway then applies the CORS allowlist and matching CSRF origin checks.

Important

The Gateway still owns active run tasks in process, so production defaults to a single Gateway worker (GATEWAY_WORKERS=1). The Redis stream bridge (stream_bridge.type: redis) shares SSE delivery and Last-Event-ID replay across workers, with a rolling retained-buffer TTL (stream_ttl_seconds) as a cleanup safety net. It does not make run cancellation, request de-duplication, or IM channel state fully cross-worker by itself; use single-worker Gateway or explicit sticky routing/ownership before raising GATEWAY_WORKERS.

See CONTRIBUTING.md for detailed Docker development guide.

Option 2: Local Development

If you prefer running services locally:

Prerequisite: complete the "Configuration" steps above first (make setup). make dev requires a valid config.yaml in the project root. Set DEER_FLOW_PROJECT_ROOT to define that root explicitly, or DEER_FLOW_CONFIG_PATH to point at a specific config file. Runtime state defaults to .deer-flow under the project root and can be moved with DEER_FLOW_HOME; skills default to skills/ under the project root and can be moved with DEER_FLOW_SKILLS_PATH. Run make doctor to verify your setup before starting. On Windows, run the local development flow from Git Bash. Native cmd.exe and PowerShell shells are not supported for the bash-based service scripts, and WSL is not guaranteed because some scripts rely on Git for Windows utilities such as cygpath.

1. Check prerequisites :

   make check  # Verifies Node.js 22+, pnpm, uv, nginx
   

2. Install dependencies :

   make install  # Install backend + frontend dependencies + pre-commit hooks
   

3. (Optional) Pre-pull sandbox image :

   # Recommended if using Docker/Container-based sandbox
   make setup-sandbox
   

4. (Optional) Load sample memory data for local review :

   python scripts/load_memory_sample.py
   

This copies the sample fixture into the default local runtime memory file so reviewers can immediately test Settings > Memory. See backend/docs/MEMORY_SETTINGS_REVIEW.md for the shortest review flow.

5. Start services :

6. Access : http://localhost:2026

DeerFlow runs the agent runtime inside the Gateway API. Development mode enables hot-reload; production mode uses a pre-built frontend.

| Local Foreground | Local Daemon | Docker Dev | Docker Prod
---|---|---|---|---
Dev | ./scripts/serve.sh --dev
make dev | ./scripts/serve.sh --dev --daemon
make dev-daemon | ./scripts/docker.sh start
make docker-start | —
Prod | ./scripts/serve.sh --prod
make start | ./scripts/serve.sh --prod --daemon
make start-daemon | — | ./scripts/deploy.sh
make up
Action | Local | Docker Dev | Docker Prod
---|---|---|---
Stop | ./scripts/serve.sh --stop
make stop | ./scripts/docker.sh stop
make docker-stop | ./scripts/deploy.sh down
make down
Restart | ./scripts/serve.sh --restart [flags] | ./scripts/docker.sh restart | —

Gateway owns /api/langgraph/* and translates those public LangGraph-compatible paths to its native /api/* routers behind nginx.

Docker Production Deployment

deploy.sh supports building and starting separately:

# One-step (build + start)
deploy.sh

# Two-step (build once, start later)
deploy.sh build              # build all images
deploy.sh start              # start pre-built images

# Stop
deploy.sh down

DeerFlow supports multiple sandbox execution modes:

• Local Execution (runs sandbox code directly on the host machine)
• Docker Execution (runs sandbox code in isolated Docker containers)
• Docker Execution with Kubernetes (runs sandbox code in Kubernetes pods via provisioner service)

For Docker development, service startup follows config.yaml sandbox mode. In Local/Docker modes, provisioner is not started.

See the Sandbox Configuration Guide to configure your preferred mode.

DeerFlow supports configurable MCP servers and skills to extend its capabilities. For HTTP/SSE MCP servers, OAuth token flows are supported (client_credentials, refresh_token). For stdio MCP servers, per-tool call timeouts can be configured with tool_call_timeout. See the MCP Server Guide for detailed instructions.

DeerFlow supports receiving tasks from messaging apps. Channels auto-start when configured — no public IP required for any of them.

DeerFlow can also expose user-owned IM channel connections in the workspace UI. When channel_connections is enabled, logged-in users can bind Telegram, Slack, Discord, Feishu/Lark, DingTalk, WeChat, or WeCom from the sidebar / Settings > Channels. It reuses the existing outbound channels.* transports, so no public IP or provider callback URL is required. Incoming IM messages then run under the connected DeerFlow user account. See IM Channel Connections for setup and security notes.

Channel	Transport	Difficulty
Telegram	Bot API (long-polling)	Easy
Slack	Socket Mode	Moderate
Feishu / Lark	WebSocket	Moderate
WeChat	Tencent iLink (long-polling)	Moderate
WeCom	WebSocket	Moderate
DingTalk	Stream Push (WebSocket)	Moderate

Configuration inconfig.yaml:

channels:
  # LangGraph-compatible Gateway API base URL (default: http://localhost:8001/api)
  langgraph_url: http://localhost:8001/api
  # Gateway API URL (default: http://localhost:8001)
  gateway_url: http://localhost:8001

  # Optional: global session defaults for all mobile channels
  session:
    assistant_id: lead_agent  # or a custom agent name; custom agents are routed via 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       # China (default)
    # domain: https://open.larksuite.com   # International

  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: []               # empty = allow all

  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []               # empty = allow all

  wechat:
    enabled: false
    bot_token: $WECHAT_BOT_TOKEN
    ilink_bot_id: $WECHAT_ILINK_BOT_ID
    qrcode_login_enabled: true      # optional: allow first-time QR bootstrap when bot_token is absent
    allowed_users: []               # empty = allow all
    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

    # Optional: per-channel / per-user session settings
    session:
      assistant_id: mobile-agent  # custom agent names are also supported here
      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 of your DingTalk application
    client_secret: $DINGTALK_CLIENT_SECRET     # Client Secret of your DingTalk application
    allowed_users: []                          # empty = allow all
    card_template_id: ""                       # Optional: AI Card template ID for streaming typewriter effect

Notes:

• assistant_id: lead_agent calls the default LangGraph assistant directly.
• If assistant_id is set to a custom agent name, DeerFlow still routes through lead_agent and injects that value as agent_name, so the custom agent's SOUL/config takes effect for IM channels.
• IM channel workers call Gateway's LangGraph-compatible API internally and automatically attach process-local internal auth plus the CSRF cookie/header pair required for thread and run creation.

Set the corresponding API keys in your .env file:

# 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 Setup

1. Chat with @BotFather, send /newbot, and copy the HTTP API token.
2. Set TELEGRAM_BOT_TOKEN in .env and enable the channel in config.yaml.

Slack Setup

1. Create a Slack App at api.slack.com/apps → Create New App → From scratch.
2. Under OAuth & Permissions, add Bot Token Scopes: app_mentions:read, chat:write, im:history, im:read, im:write, files:write.
3. Enable Socket Mode → generate an App-Level Token (xapp-…) with connections:write scope.
4. Under Event Subscriptions , subscribe to bot events: app_mention, message.im.
5. Set SLACK_BOT_TOKEN and SLACK_APP_TOKEN in .env and enable the channel in config.yaml.

Feishu / Lark Setup

1. Create an app on Feishu Open Platform → enable Bot capability.
2. Add permissions: im:message, im:message.p2p_msg:readonly, im:resource.
3. Under Events , subscribe to im.message.receive_v1 and select Long Connection mode.
4. Copy the App ID and App Secret. Set FEISHU_APP_ID and FEISHU_APP_SECRET in .env and enable the channel in config.yaml.

WeChat Setup

1. Enable the wechat channel in config.yaml.
2. Either set WECHAT_BOT_TOKEN in .env, or set qrcode_login_enabled: true for first-time QR bootstrap.
3. When bot_token is absent and QR bootstrap is enabled, watch backend logs for the QR content returned by iLink and complete the binding flow.
4. After the QR flow succeeds, DeerFlow persists the acquired token under state_dir for later restarts.
5. For Docker Compose deployments, keep state_dir on a persistent volume so the get_updates_buf cursor and saved auth state survive restarts.

WeCom Setup

1. Create a bot on the WeCom AI Bot platform and obtain the bot_id and bot_secret.
2. Enable channels.wecom in config.yaml and fill in bot_id / bot_secret.
3. Set WECOM_BOT_ID and WECOM_BOT_SECRET in .env.
4. Make sure backend dependencies include wecom-aibot-python-sdk. The channel uses a WebSocket long connection and does not require a public callback URL.
5. The current integration supports inbound text, image, and file messages. Final images/files generated by the agent are also sent back to the WeCom conversation.

DingTalk Setup

1. Create a DingTalk application in the DingTalk Developer Console and enable Robot capability.
2. Set the message receiving mode to Stream Mode in the robot configuration page.
3. Copy the Client ID and Client Secret, set DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET in .env, and enable the channel in config.yaml.
4. (Optional) To enable streaming AI Card replies (typewriter effect), create an AI Card template on the DingTalk Card Platform, then set card_template_id in config.yaml to the template ID. You also need to apply for the Card.Streaming.Write and Card.Instance.Write permissions.

When DeerFlow runs in Docker Compose, IM channels execute inside the gateway container. In that case, do not point channels.langgraph_url or channels.gateway_url at localhost; use container service names such as http://gateway:8001/api and http://gateway:8001, or set DEER_FLOW_CHANNELS_LANGGRAPH_URL and DEER_FLOW_CHANNELS_GATEWAY_URL.

Commands

Once a channel is connected, you can interact with DeerFlow directly from the chat:

Command	Description
/new	Start a new conversation
/status	Show current thread info
/models	List available models
/memory	View memory
/help	Show help

Messages without a command prefix are treated as regular chat — DeerFlow creates a thread and responds conversationally.

Request Trace Correlation

Gateway request trace correlation is disabled by default so existing HTTP responses and log formats stay unchanged. To enable it, set:

logging:
  enhance:
    enabled: true
    format: text

When enabled, every Gateway HTTP response includes X-Trace-Id, logs include trace_id, and Langfuse traces created by that request include metadata.deerflow_trace_id with the same value.

DeerFlow has built-in LangSmith integration for observability. When enabled, all LLM calls, agent runs, and tool executions are traced and visible in the LangSmith dashboard.

Add the following to your .env file:

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

DeerFlow also supports Langfuse observability for LangChain-compatible runs.

Add the following to your .env file:

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

If you are using a self-hosted Langfuse instance, set LANGFUSE_BASE_URL to your deployment URL.

Trace correlation fields. Every agent run is annotated with Langfuse's reserved trace attributes so the Sessions and Users pages light up automatically:

• session_id = LangGraph thread_id — groups every trace of the same conversation
• user_id = effective user from get_effective_user_id() (falls back to default in no-auth mode)
• trace_name = assistant id (defaults to lead-agent)
• tags = [env:<DEER_FLOW_ENV>, model:<model_name>] (omitted when not set)
• metadata.deerflow_trace_id = DeerFlow request correlation id, matching X-Trace-Id when request trace correlation is enabled

These are injected into RunnableConfig.metadata at the graph invocation root for both the gateway path (runtime/runs/worker.py::run_agent) and the embedded path (client.py::DeerFlowClient.stream), so any LangChain-compatible callback can read them. Set DEER_FLOW_ENV (or ENVIRONMENT) to tag traces by deployment environment.

If both LangSmith and Langfuse are enabled, DeerFlow attaches both tracing callbacks and reports the same model activity to both systems.

If a provider is explicitly enabled but missing required credentials, or if its callback fails to initialize, DeerFlow fails fast when tracing is initialized during model creation and the error message names the provider that caused the failure.

For Docker deployments, tracing is disabled by default. Set LANGSMITH_TRACING=true and LANGSMITH_API_KEY in your .env to enable it.

From Deep Research to Super Agent Harness

DeerFlow started as a Deep Research framework — and the community ran with it. Since launch, developers have pushed it far beyond research: building data pipelines, generating slide decks, spinning up dashboards, automating content workflows. Things we never anticipated.

That told us something important: DeerFlow wasn't just a research tool. It was a harness — a runtime that gives agents the infrastructure to actually get work done.

So we rebuilt it from scratch.

DeerFlow 2.0 is no longer a framework you wire together. It's a super agent harness — batteries included, fully extensible. Built on LangGraph and LangChain, it ships with everything an agent needs out of the box: a filesystem, memory, skills, sandbox-aware execution, and the ability to plan and spawn sub-agents for complex, multi-step tasks.

Use it as-is. Or tear it apart and make it yours.

Skills are what make DeerFlow do almost anything.

A standard Agent Skill is a structured capability module — a Markdown file that defines a workflow, best practices, and references to supporting resources. DeerFlow ships with built-in skills for research, report generation, slide creation, web pages, image and video generation, and more. But the real power is extensibility: add your own skills, replace the built-in ones, or combine them into compound workflows.

Skills are loaded progressively — only when the task needs them, not all at once. This keeps the context window lean and makes DeerFlow work well even with token-sensitive models.

Users can explicitly activate an enabled skill for a single turn by starting the request with /skill-name, for example /data-analysis analyze uploads/foo.csv. DeerFlow loads that skill's SKILL.md as hidden current-turn context while leaving the base prompt limited to skill metadata. Slash activation respects disabled skills, custom-agent skill whitelists, and existing channel commands such as /new and /help.

When you install .skill archives through the Gateway, DeerFlow accepts standard optional frontmatter metadata such as version, author, and compatibility instead of rejecting otherwise valid external skills.

Tools follow the same philosophy. DeerFlow comes with a core toolset — web search, web fetch, rendered web capture, file operations, bash execution — and supports custom tools via MCP servers and Python functions. Swap anything. Add anything.

Gateway-generated follow-up suggestions now normalize both plain-string model output and block/list-style rich content before parsing the JSON array response, so provider-specific content wrappers do not silently drop suggestions.

Interrupted first-turn runs still persist a fallback conversation title, so stopping a streaming response does not leave the thread as "Untitled" after refresh.

In the Web UI, completed assistant turns can be branched into a new main conversation. The new thread starts from that turn's checkpoint. Because workspace files are not checkpointed, the branch only receives a best-effort copy of the current workspace when you branch from the latest turn; branching from an older turn keeps just the restored message history so the branch never inherits files that were created in a later part of the conversation.

# Paths inside the sandbox container
/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      ← yours

The claude-to-deerflow skill lets you interact with a running DeerFlow instance directly from Claude Code. Send research tasks, check status, manage threads — all without leaving the terminal.

Install the skill :

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

Then make sure DeerFlow is running (default at http://localhost:2026) and use the /claude-to-deerflow command in Claude Code.

What you can do :

• Send messages to DeerFlow and get streaming responses
• Choose execution modes: flash (fast), standard, pro (planning), ultra (sub-agents)
• Check DeerFlow health, list models/skills/agents
• Manage threads and conversation history
• Upload files for analysis

Environment variables (optional, for custom endpoints):

DEERFLOW_URL=http://localhost:2026            # Unified proxy base URL
DEERFLOW_GATEWAY_URL=http://localhost:2026    # Gateway API
DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph  # LangGraph API

See skills/public/claude-to-deerflow/SKILL.md for the full API reference.

Use /goal <completion condition> to attach one active completion condition to the current thread. The goal is thread-scoped state, not a skill activation, so it stays active across turns until DeerFlow determines it has been satisfied or you clear it.

Supported commands:

/goal finish the implementation and make all tests pass
/goal              # show the active goal
/goal clear        # clear it

After each Gateway-backed run, DeerFlow evaluates the visible conversation against the active goal with a non-thinking evaluator model. The evaluator must return a typed blocker (missing_evidence, needs_user_input, run_failed, external_wait, or goal_not_met_yet) plus visible evidence. DeerFlow only injects a hidden continuation when the latest assistant turn is durably checkpointed, the blocker is goal_not_met_yet, the thread did not change during evaluation, and the no-progress breaker has not fired. The safety cap defaults to 8 hidden continuations, and repeated identical non-progress evaluations stop after 2 attempts. /goal clear and any user-authored new input win over queued continuations. When the goal is satisfied, DeerFlow clears it automatically and publishes the updated thread state.

The Web UI shows the active goal above the composer. The same command is available from the TUI and supported IM channels. In the Web UI and supported IM channels, setting /goal <completion condition> also starts a run with the condition as the task; status and clear commands only manage goal state.

Complex tasks rarely fit in a single pass. DeerFlow decomposes them.

The lead agent can spawn sub-agents on the fly — each with its own scoped context, tools, and termination conditions. Sub-agents run in parallel when possible, report back structured results, and the lead agent synthesizes everything into a coherent output. When token usage tracking is enabled, completed sub-agent usage is attributed back to the dispatching step.

This is how DeerFlow handles tasks that take minutes to hours: a research task might fan out into a dozen sub-agents, each exploring a different angle, then converge into a single report — or a website — or a slide deck with generated visuals. One harness, many hands.

DeerFlow doesn't just talk about doing things. It has its own computer.

Each task gets its own execution environment with a full filesystem view — skills, workspace, uploads, outputs. The agent reads, writes, and edits files. It can view images and, when configured safely, execute shell commands.

After each run, DeerFlow records a workspace change summary for the run-owned workspace and outputs directories. The Web UI shows a compact "files changed" badge on the assistant turn; opening it reveals created, modified, and deleted files with text diffs when safe to display. Uploads are excluded because they are user inputs, not agent-generated changes. Large, binary, or sensitive-looking files are shown as metadata only.

With AioSandboxProvider, shell execution runs inside isolated containers. With LocalSandboxProvider, file tools still map to per-thread directories on the host, but host bash is disabled by default because it is not a secure isolation boundary. Re-enable host bash only for fully trusted local workflows. Host bash commands have a wall-clock timeout, and long-lived processes should be started in the background with output redirected to a workspace log.

This is the difference between a chatbot with tool access and an agent with an actual execution environment.

# Paths inside the sandbox container
/mnt/user-data/
├── uploads/          ← your files
├── workspace/        ← agents' working directory
└── outputs/          ← final deliverables

Isolated Sub-Agent Context : Each sub-agent runs in its own isolated context. This means that the sub-agent will not be able to see the context of the main agent or other sub-agents. This is important to ensure that the sub-agent is able to focus on the task at hand and not be distracted by the context of the main agent or other sub-agents.

Summarization : Within a session, DeerFlow manages context aggressively — summarizing completed sub-tasks, offloading intermediate results to the filesystem, compressing what's no longer immediately relevant. This lets it stay sharp across long, multi-step tasks without blowing the context window.

Strict Tool-Call Recovery : When a provider or middleware interrupts a tool-call loop, DeerFlow now strips provider-level raw tool-call metadata on forced-stop assistant messages and injects placeholder tool results for dangling calls before the next model invocation. This keeps OpenAI-compatible reasoning models that strictly validate tool_call_id sequences from failing with malformed history errors.

Most agents forget everything the moment a conversation ends. DeerFlow remembers.

Across sessions, DeerFlow builds a persistent memory of your profile, preferences, and accumulated knowledge. The more you use it, the better it knows you — your writing style, your technical stack, your recurring workflows. Memory is stored locally and stays under your control.

Memory updates now skip duplicate fact entries at apply time, so repeated preferences and context do not accumulate endlessly across sessions.

DeerFlow is model-agnostic — it works with any LLM that implements the OpenAI-compatible API. That said, it performs best with models that support:

• Long context windows (100k+ tokens) for deep research and multi-step tasks
• Reasoning capabilities for adaptive planning and complex decomposition
• Multimodal inputs for image understanding and video comprehension
• Strong tool-use for reliable function calling and structured outputs

DeerFlow can be used as an embedded Python library without running the full HTTP services. The DeerFlowClient provides direct in-process access to all agent and Gateway capabilities, returning the same response schemas as the HTTP Gateway API. The HTTP Gateway also exposes DELETE /api/threads/{thread_id} to remove DeerFlow-managed local thread data after the LangGraph thread itself has been deleted:

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

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

# Streaming (LangGraph SSE protocol: 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"])

# Configuration & management — returns Gateway-aligned dicts
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")

All dict-returning methods are validated against Gateway Pydantic response models in CI (TestGatewayConformance), ensuring the embedded client stays in sync with the HTTP API schemas. See backend/packages/harness/deerflow/client.py for full API documentation.

DeerFlow now includes a first-class scheduled-task MVP in the workspace.

Current MVP capabilities:

• Manage tasks at /workspace/scheduled-tasks
• Choose whether each scheduled task reuses a thread or creates a fresh thread per run
• Support once and cron schedules
• Run background scheduled executions as non-interactive DeerFlow runs (ask_clarification is not exposed there)
• Use skip overlap behavior for due cron executions that collide with an active run on the same reused thread
• Pause, resume, trigger, inspect history, and delete tasks
• Execute scheduled work through the normal DeerFlow run lifecycle

Current MVP limits:

• No conversation-created schedule_task tool yet
• No text-only notification jobs
• No channel or GitHub dispatch targets
• No interval schedule type in this first cut

Enable background polling with config.yaml -> scheduler.enabled. Manual trigger uses the same scheduled-task resource and execution path.

deerflow is a terminal-native workbench for people who live in the shell. It runs embedded over DeerFlowClient — no Gateway, frontend, nginx, or Docker required — while honoring the same config.yaml, checkpointer, skills, memory, MCP, and sandbox settings as the rest of DeerFlow.

uv pip install 'deerflow-harness[tui]'        # optional 'textual' dependency

deerflow                                      # launch the terminal UI (TTY required)
deerflow --continue                           # resume the most recent thread
deerflow --resume THREAD                      # resume a thread by id
deerflow --print "summarize this repo"        # headless one-shot answer to stdout
deerflow --json  "hello"                       # headless newline-delimited StreamEvents

A keyboard-driven chat surface with a streaming transcript (Markdown-rendered answers), compact tool-activity cards, a / slash-command palette, /goal goal management, /model and /threads pickers, input history, and Esc / Ctrl+C interrupt. Sessions opened in the TUI also appear in the Web UI sidebar — it writes the shared thread store under the local default user, so terminal and web stay in sync without running the Gateway.

See backend/docs/TUI.md for the full guide.

Improper Deployment May Introduce Security Risks

DeerFlow has key high-privilege capabilities including system command execution, resource operations, and business logic invocation , and is designed by default to be deployed in a local trusted environment (accessible only via the 127.0.0.1 loopback interface). If you deploy the agent in untrusted environments — such as LAN networks, public cloud servers, or other multi-endpoint accessible environments — without strict security measures, it may introduce security risks, including:

• Unauthorized illegal invocation : Agent functionality could be discovered by unauthorized third parties or malicious internet scanners, triggering bulk unauthorized requests that execute high-risk operations such as system commands and file read/write, potentially causing serious security consequences.
• Compliance and legal risks : If the agent is illegally invoked to conduct cyberattacks, data theft, or other illegal activities, it may result in legal liability and compliance risks.

Note: We strongly recommend deploying DeerFlow in a local trusted network environment. If you need cross-device or cross-network deployment, you must implement strict security measures, such as:

• IP allowlist : Use iptables, or deploy hardware firewalls / switches with Access Control Lists (ACL), to configure IP allowlist rules and deny access from all other IP addresses.
• Authentication gateway : Configure a reverse proxy (e.g., nginx) and enable strong pre-authentication , blocking any unauthenticated access.
• Network isolation : Where possible, place the agent and trusted devices in the same dedicated VLAN , isolated from other network devices.
• Stay updated : Continue to follow DeerFlow's security feature updates.

We welcome contributions! Please see CONTRIBUTING.md for development setup, workflow, and guidelines.

Regression coverage includes Docker sandbox mode detection and provisioner kubeconfig-path handling tests in backend/tests/. Backend blocking-IO diagnostics are available from the repository root with make detect-blocking-io: it statically scans backend business code for blocking IO that may run on the backend event loop, prints a concise summary, and writes complete JSON findings to .deer-flow/blocking-io-findings.json. The JSON includes compact review records with priority, location, blocking_call, event_loop_exposure, reason, and code. Gateway artifact serving now forces active web content types (text/html, application/xhtml+xml, image/svg+xml) to download as attachments instead of inline rendering, reducing XSS risk for generated artifacts.

This project is open source and available under the MIT License.

DeerFlow is built upon the incredible work of the open-source community. We are deeply grateful to all the projects and contributors whose efforts have made DeerFlow possible. Truly, we stand on the shoulders of giants.

We would like to extend our sincere appreciation to the following projects for their invaluable contributions:

• LangChain : Their exceptional framework powers our LLM interactions and chains, enabling seamless integration and functionality.
• LangGraph : Their innovative approach to multi-agent orchestration has been instrumental in enabling DeerFlow's sophisticated workflows.

These projects exemplify the transformative power of open-source collaboration, and we are proud to build upon their foundations.

A heartfelt thank you goes out to the core authors of DeerFlow, whose vision, passion, and dedication have brought this project to life:

Your unwavering commitment and expertise have been the driving force behind DeerFlow's success. We are honored to have you at the helm of this journey.