GitHub - bytedance/deer-flow：一个开源的长时域超级智能体框架，能够进行研究、编码和创作。

原创于 2026-06-22 10:33:33 发布 · 669 阅读

1 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

标签

#AI #自动化

🦌 DeerFlow - 2.0

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

2026 年 2 月 28 日，DeerFlow 在 2.0 版本发布后荣登 GitHub Trending 🏆 第一名。衷心感谢我们出色的社区——是你们创造了这一切！💪🔥

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

deer-flow-720p.mp4

Note

DeerFlow 2.0 是一次从头重写。 它与 v1 没有任何共同代码。如果你在寻找原始的深度研究框架，它维护在 1.x 分支——该分支仍欢迎贡献。主动开发已迁移至 2.0。

官方网站

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

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

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

InfoQuest

DeerFlow 已新集成由 BytePlus 自主研发的智能搜索与抓取工具集——InfoQuest（支持免费在线体验）

🦌 DeerFlow - 2.0 官方网站
字节跳动火山引擎编程计划
InfoQuest
目录
一行命令 Agent 配置
快速开始配置
运行应用部署规格
方式一：Docker（推荐）
方式二：本地开发
高级沙箱模式
MCP Server
IM 频道
LangSmith 追踪
Langfuse 追踪
同时使用两个提供商
从深度研究到超级 Agent 框架
核心功能技能与工具 Claude Code 集成
子 Agent
沙箱与文件系统
上下文工程
长期记忆
推荐模型
内嵌 Python 客户端
文档
⚠️ 安全须知不当部署可能引入安全风险
安全建议
贡献
许可证
致谢主要贡献者
Star 历史

一行命令 Agent 配置

如果你使用 Claude Code、Codex、Cursor、Windsurf 或其他编程 Agent，可以用一句话将配置说明交给它：

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

该提示词面向编程 Agent。它会告诉 Agent：如有需要则克隆仓库，有条件时选择 Docker，最终给出确切的下一条命令以及用户仍需提供的缺失配置。

快速开始

配置

克隆 DeerFlow 仓库 git clone https://github.com/bytedance/deer-flow.git cd deer-flow
运行配置向导 在项目根目录（deer-flow/）下执行：make setup 这将启动一个交互式向导，引导你选择 LLM 提供商、可选的网络搜索，以及执行/安全偏好（如沙箱模式、bash 访问权限和文件写入工具）。向导会生成一个最小化的 config.yaml 并将你的密钥写入 .env，整个过程约需 2 分钟。向导还支持配置可选的网络搜索提供商，也可以暂时跳过。随时运行 make doctor 以验证你的配置并获取可操作的修复提示。高级/手动配置：如果你更倾向于直接编辑 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 agent 条目与模型提供商分开配置——如果你配置了 acp_agents.codex，请将其指向 Codex ACP 适配器，例如 npx -y @zed-industries/codex-acp
在 macOS 上，如有需要请显式导出 Claude Code 认证信息：

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

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

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

运行应用

部署规格

在选择如何运行 DeerFlow 时，请参考下表作为实用起点：

以上数字仅涵盖 DeerFlow 本身。如果你同时托管本地 LLM，请单独为该服务评估规格。
Linux 加 Docker 是持久化服务器的推荐部署目标。macOS 和 Windows 最好作为开发或评估环境使用。
如果 CPU 或内存使用率持续高位，请先减少并发运行数，再考虑升级到更高规格档次。

方式一：Docker（推荐）

开发模式（热重载，源码挂载）：

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 仅在 config.yaml 使用 provisioner 模式（sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider 配合 provisioner_url）时才启动 provisioner。

Docker 构建默认使用上游 uv 镜像仓库。如果你在受限网络中需要更快的镜像源，请在运行 make docker-init 或 make docker-start 之前导出 UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple 和 NPM_REGISTRY=https://registry.npmmirror.com。

后端进程会在下次访问配置时自动读取 config.yaml 的更改，因此在开发过程中更新模型元数据无需手动重启。

Tip

在 Linux 上，如果基于 Docker 的命令因 permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock 而失败，请将你的用户添加到 docker 组并重新登录后再试。完整修复方法请参见 CONTRIBUTING.md。

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

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

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

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

Important

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

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

方式二：本地开发

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

前提条件：请先完成上方的"配置"步骤（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）。

检查前提条件：make check # Verifies Node.js 22+, pnpm, uv, nginx
安装依赖：make install # Install backend + frontend dependencies + pre-commit hooks
（可选）预拉取沙箱镜像：# Recommended if using Docker/Container-based sandbox make setup-sandbox
（可选）加载示例记忆数据以供本地查看：python scripts/load_memory_sample.py 该命令将示例 fixture 复制到默认本地运行时记忆文件，以便评审人员可立即测试 Settings > Memory。最短评审流程请参见 backend/docs/MEMORY_SETTINGS_REVIEW.md。
启动服务：make dev
访问：http://localhost:2026

启动模式

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

| 操作 | 本地 | Docker 开发 | Docker 生产 |

| 重启 | ./scripts/serve.sh --restart [flags] | ./scripts/docker.sh restart | — |

Gateway 拥有 /api/langgraph/* 并在 nginx 后将这些公共的 LangGraph 兼容路径转换为其原生 /api/* 路由器。

Docker 生产部署

deploy.sh 支持分开构建和启动：

# 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 支持多种沙箱执行模式：

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

在 Docker 开发模式下，服务启动遵循 config.yaml 沙箱模式。在本地/Docker 模式下，provisioner 不会被启动。

参见沙箱配置指南以配置你偏好的模式。

MCP Server

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

IM Channels

DeerFlow 支持从即时通讯应用接收任务。配置完成后，各 Channel 会自动启动——所有 Channel 均无需公网 IP。

DeerFlow 还可以在工作区 UI 中向用户开放自有的 IM Channel 连接。当 channel_connections 启用时，已登录用户可通过侧边栏或"Settings > Channels"绑定 Telegram、Slack、Discord、飞书/Lark、DingTalk、微信或企业微信。该功能复用已有的出站 channels.* 传输通道，因此无需公网 IP 或服务商回调 URL。绑定后，IM 消息的处理将使用所连接的 DeerFlow 用户账号。有关配置和安全说明，请参阅 IM Channel Connections。

| Channel | Transport | Difficulty |

| Telegram | Bot API（长轮询） | 简单 |

| Slack | Socket Mode | 中等 |

| 飞书 / Lark | WebSocket | 中等 |

| 微信 | 腾讯 iLink（长轮询） | 中等 |

| 企业微信 | WebSocket | 中等 |

| DingTalk | Stream Push（WebSocket） | 中等 |

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

注意事项：

assistant_id: lead_agent 直接调用默认的 LangGraph 助手。
如果 assistant_id 设置为自定义 Agent 名称，DeerFlow 仍会通过 lead_agent 路由，并将该值作为 agent_name 注入，从而使自定义 Agent 的 SOUL/config 在 IM Channel 中生效。
IM Channel Worker 在内部调用 Gateway 的 LangGraph 兼容 API，并自动附加进程本地内部鉴权信息，以及线程和运行创建所需的 CSRF cookie/header 对。

在 .env 文件中设置对应的 API 密钥：

# Telegram TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ # Slack SLACK_BOT_TOKEN=xoxb-... SLACK_APP_TOKEN=xapp-... # Feishu / Lark FEISHU_APP_ID=cli_xxxx FEISHU_APP_SECRET=your_app_secret # WeChat iLink WECHAT_BOT_TOKEN=your_ilink_bot_token WECHAT_ILINK_BOT_ID=your_ilink_bot_id # WeCom WECOM_BOT_ID=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。
在 .env 中设置 TELEGRAM_BOT_TOKEN，并在 config.yaml 中启用该 Channel。

Slack 配置

前往 api.slack.com/apps → Create New App → From scratch，创建一个 Slack 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 下，订阅 Bot 事件：app_mention、message.im。
在 .env 中设置 SLACK_BOT_TOKEN 和 SLACK_APP_TOKEN，并在 config.yaml 中启用该 Channel。

飞书 / Lark 配置

在飞书开放平台创建应用 → 启用机器人能力。
添加权限：im:message、im:message.p2p_msg:readonly、im:resource。
在事件下，订阅 im.message.receive_v1 并选择长连接模式。
复制 App ID 和 App Secret，在 .env 中设置 FEISHU_APP_ID 和 FEISHU_APP_SECRET，并在 config.yaml 中启用该 Channel。

微信配置

在 config.yaml 中启用 wechat Channel。
在 .env 中设置 WECHAT_BOT_TOKEN，或设置 qrcode_login_enabled: true 以进行首次二维码引导绑定。
当 bot_token 不存在且启用了二维码引导时，请查看后端日志中 iLink 返回的二维码内容，并完成绑定流程。
二维码流程成功后，DeerFlow 会将获取到的 token 持久化保存至 state_dir，以便后续重启使用。
对于 Docker Compose 部署，请将 state_dir 挂载至持久化卷，以确保 get_updates_buf 游标和已保存的鉴权状态在重启后仍然有效。

企业微信配置

在企业微信 AI Bot 平台创建机器人，并获取 bot_id 和 bot_secret。
在 config.yaml 中启用 channels.wecom，并填入 bot_id / bot_secret。
在 .env 中设置 WECOM_BOT_ID 和 WECOM_BOT_SECRET。
确保后端依赖项中包含 wecom-aibot-python-sdk。该 Channel 使用 WebSocket 长连接，无需公网回调 URL。
当前集成支持接收文本、图片和文件消息。Agent 生成的最终图片/文件也会回传至企业微信会话。

DingTalk 配置

在 DingTalk 开发者后台创建 DingTalk 应用，并启用机器人能力。
在机器人配置页面，将消息接收模式设置为 Stream 模式。
复制 Client ID 和 Client Secret，在 .env 中设置 DINGTALK_CLIENT_ID 和 DINGTALK_CLIENT_SECRET，并在 config.yaml 中启用该 Channel。
（可选） 如需启用流式 AI 卡片回复（打字机效果），请在 DingTalk 卡片平台创建一个 AI 卡片模板，然后将 config.yaml 中的 card_template_id 设置为该模板 ID。同时还需申请 Card.Streaming.Write 和 Card.Instance.Write 权限。

当 DeerFlow 在 Docker Compose 中运行时，IM Channel 在 gateway 容器内执行。此时，请勿将 channels.langgraph_url 或 channels.gateway_url 指向 localhost，而应使用容器服务名称，例如 http://gateway:8001/api 和 http://gateway:8001，或设置 DEER_FLOW_CHANNELS_LANGGRAPH_URL 和 DEER_FLOW_CHANNELS_GATEWAY_URL。

命令

Channel 连接完成后，您可以直接在聊天中与 DeerFlow 交互：

| 命令 | 说明 |

| /new | 开始新对话 |

| /status | 显示当前线程信息 |

| /models | 列出可用模型 |

| /memory | 查看记忆 |

| /help | 显示帮助 |

不带命令前缀的消息将被视为普通聊天——DeerFlow 会创建一个线程并以对话方式回复。

LangSmith Tracing

DeerFlow 内置了 LangSmith 集成，用于可观测性。启用后，所有 LLM 调用、Agent 运行和工具执行均会被追踪，并在 LangSmith 控制台中可见。

将以下内容添加至 .env 文件：

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

Langfuse Tracing

DeerFlow 还支持 Langfuse 可观测性，适用于 LangChain 兼容的运行。

将以下内容添加至 .env 文件：

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

如果您使用的是自托管 Langfuse 实例，请将 LANGFUSE_BASE_URL 设置为您的部署 URL。

Trace 关联字段。 每次 Agent 运行都会附加 Langfuse 的保留 Trace 属性，以便 Sessions 和 Users 页面自动生效：

session_id = LangGraph thread_id —— 将同一对话的所有 Trace 归组
user_id = 来自 get_effective_user_id() 的有效用户（无鉴权模式下回退为 default）
trace_name = 助手 ID（默认为 lead-agent）
tags = [env: , model: ]（未设置时省略）

这些属性在图调用根节点处注入至 RunnableConfig.metadata，对 Gateway 路径（runtime/runs/worker.py::run_agent）和嵌入路径（client.py::DeerFlowClient.stream）均适用，因此任何 LangChain 兼容的回调都可以读取它们。设置 DEER_FLOW_ENV（或 ENVIRONMENT）可按部署环境为 Trace 打标签。

同时使用两个提供商

如果同时启用了 LangSmith 和 Langfuse，DeerFlow 会同时附加两个 Tracing 回调，并将相同的模型活动上报至两个系统。

如果某个提供商被显式启用但缺少必要凭据，或其回调初始化失败，DeerFlow 会在模型创建期间初始化 Tracing 时快速失败，并在错误信息中指明导致失败的提供商。

对于 Docker 部署，Tracing 默认禁用。在 .env 中设置 LANGSMITH_TRACING=true 和 LANGSMITH_API_KEY 可启用该功能。

从深度研究到超级 Agent 底座

DeerFlow 最初是一个深度研究框架——而社区将它推得更远。自发布以来，开发者们将它的应用场景远远拓展到了研究之外：构建数据管道、生成幻灯片、搭建仪表盘、自动化内容工作流。这些都是我们从未预料到的。

这让我们意识到一件重要的事：DeerFlow 不只是一个研究工具，它是一个底座——一个能让 Agent 真正完成工作的运行时基础设施。

于是我们从头重建。

DeerFlow 2.0 不再是一个需要手动拼装的框架，而是一个超级 Agent 底座——开箱即用，完全可扩展。它基于 LangGraph 和 LangChain 构建，内置了 Agent 所需的一切：文件系统、记忆、技能、沙箱感知执行，以及针对复杂多步任务的规划与子 Agent 派生能力。

按原样使用，或拆开来按你的方式重塑。

核心功能

Skills & Tools

技能（Skill）让 DeerFlow 几乎能做任何事。

标准的 Agent Skill 是一个结构化的能力模块——一个 Markdown 文件，定义了工作流、最佳实践以及对辅助资源的引用。DeerFlow 内置了用于研究、报告生成、幻灯片制作、网页生成、图像和视频生成等技能。但真正的威力在于可扩展性：添加你自己的技能、替换内置技能，或将它们组合成复合工作流。

技能按需加载——仅在任务需要时加载，而非全部一次性加载。这使上下文窗口保持精简，让 DeerFlow 在 Token 敏感的模型下也能良好运行。

用户可以在请求开头使用 /skill-name 为单次对话显式激活某个已启用的技能，例如 /data-analysis analyze uploads/foo.csv。DeerFlow 会将该技能的 SKILL.md 作为隐藏的当前轮上下文加载，同时将基础提示词限制为技能元数据。Slash 激活方式遵守技能禁用设置、自定义 Agent 技能白名单，以及现有的 Channel 命令（如 /new 和 /help）。

通过 Gateway 安装 .skill 归档包时，DeerFlow 支持标准的可选前置元数据（frontmatter），如 version、author 和 compatibility，不会因此拒绝本身有效的外部技能。

工具遵循同样的设计理念。DeerFlow 内置了一套核心工具集——网页搜索、网页抓取、文件操作、Bash 执行——并通过 MCP 服务器和 Python 函数支持自定义工具。随意替换，随意添加。

Gateway 生成的后续建议在解析 JSON 数组响应前，现在会对纯字符串模型输出和 block/list 形式的富内容进行统一规范化处理，从而避免提供商特定的内容包装器静默丢弃建议。

# 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

Claude Code 集成

claude-to-deerflow 技能让你可以直接从 Claude Code 与运行中的 DeerFlow 实例交互。发送研究任务、查看状态、管理线程——无需离开终端。

安装技能：

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

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

你可以做到的事：

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

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

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

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

Sub-Agents

复杂任务很少能在单次执行中完成。DeerFlow 会对其进行分解。

主导 Agent 可以动态生成子 Agent——每个子 Agent 都有其独立的上下文范围、工具集和终止条件。子 Agent 在条件允许时并行运行，返回结构化结果，再由主导 Agent 将所有内容综合为连贯的输出。启用 token 用量追踪后，已完成的子 Agent 用量将归因到对应的调度步骤。

这就是 DeerFlow 处理耗时数分钟乃至数小时任务的方式：一个研究任务可能会扇出为十几个子 Agent，各自从不同角度展开探索，最终汇聚成一份完整报告——或一个网站——或一份附带生成视觉素材的幻灯片。一个框架，众多双手。

Sandbox & File System

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

每个任务都拥有独立的执行环境，包含完整的文件系统视图——技能、工作区、上传文件、输出结果。Agent 可以读取、写入和编辑文件，可以查看图片，在安全配置下还可以执行 shell 命令。

使用 AioSandboxProvider 时，shell 执行在隔离容器内运行。使用 LocalSandboxProvider 时，文件工具仍会映射到宿主机上按线程划分的目录，但宿主机 bash 默认禁用，因为它并非安全的隔离边界。仅在完全可信的本地工作流中才应重新启用宿主机 bash。

这就是"拥有工具访问权限的聊天机器人"与"拥有真实执行环境的 Agent"之间的本质区别。

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

Context Engineering

隔离的子 Agent 上下文：每个子 Agent 在独立的上下文中运行，无法访问主 Agent 或其他子 Agent 的上下文。这一设计确保子 Agent 能够专注于当前任务，不受主 Agent 或其他子 Agent 上下文的干扰。

摘要压缩：在一次会话中，DeerFlow 会主动管理上下文——对已完成的子任务进行摘要、将中间结果卸载到文件系统、压缩不再直接相关的内容。这使它能够在漫长的多步骤任务中保持专注，而不会撑爆上下文窗口。

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

Long-Term Memory

大多数 Agent 在对话结束后便会忘记一切。DeerFlow 则不然。

跨会话之间，DeerFlow 会持续构建关于你的个人档案、偏好和积累知识的持久记忆。使用越多，它对你的了解就越深——你的写作风格、技术栈、常用工作流。记忆存储在本地，完全由你掌控。

记忆更新现在会在写入时跳过重复的事实条目，避免相同的偏好和上下文在多次会话中无限累积。

Recommended Models

DeerFlow 与模型无关——它可与任何实现了 OpenAI 兼容 API 的 LLM 协同工作。尽管如此，以下能力越强，表现越佳：

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

Embedded Python Client

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

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": [...]}

所有返回 dict 的方法均在 CI 中通过 Gateway Pydantic 响应模型进行校验（TestGatewayConformance），确保嵌入式客户端与 HTTP API schema 保持同步。完整 API 文档请参见 backend/packages/harness/deerflow/client.py。

Documentation

Contributing Guide - 开发环境搭建与工作流说明
Configuration Guide - 配置与安装指南
Architecture Overview - 技术架构详解
Backend Architecture - 后端架构与 API 参考

⚠️ Security Notice

Improper Deployment May Introduce Security Risks

DeerFlow 具备系统命令执行、资源操作和业务逻辑调用等高权限核心能力，默认设计为部署在本地可信环境中（仅可通过 127.0.0.1 回环接口访问）。若在未采取严格安全措施的情况下将 Agent 部署于不可信环境——例如局域网、公有云服务器或其他多端点可访问的环境——可能引入安全风险，包括：

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

Security Recommendations

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

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

Contributing

欢迎贡献！开发环境搭建、工作流及贡献指南请参见 CONTRIBUTING.md。

回归测试覆盖范围包括 Docker sandbox 模式检测，以及 backend/tests/ 中的 provisioner kubeconfig-path 处理测试。后端阻塞 IO 诊断工具可在仓库根目录通过 make detect-blocking-io 运行：它会静态扫描后端业务代码中可能在后端事件循环上运行的阻塞 IO，打印简洁摘要，并将完整 JSON 结果写入 .deer-flow/blocking-io-findings.json。JSON 中包含紧凑的审查记录，字段包括 priority、location、blocking_call、event_loop_exposure、reason 和 code。Gateway artifact 服务现在会强制将活跃 Web 内容类型（text/html、application/xhtml+xml、image/svg+xml）以附件形式下载，而非内联渲染，从而降低生成 artifact 的 XSS 风险。