DeerFlow 是 ByteDance 開源的長程 SuperAgent harness，以 LangGraph 編排一個主代理，讓它自動把任務拆給多個隔離的子代理，在沙盒裡執行程式、查詢資料、寫出報告，並跨 session 保留結果。2.0 是從零重寫的版本，2026 年 2 月 28 日登上 GitHub Trending 第一名。本手冊涵蓋安裝步驟、能力地圖與完整任務流程示範。
DeerFlow 的官方定位：一套開源的 super agent harness，負責編排子代理、記憶與沙盒，靠可擴充的 skills 執行研究、程式撰寫與產出任務。核心概念是 harness（骨架）。它把「複雜任務如何拆開、分頭執行、再收斂成成品」這件事做成可重用的基礎建設。官方 README 的描述：一個會研究、會寫程式、會產出的長程 SuperAgent。
底層建在 LangGraph 與 LangChain 上。主代理（lead agent）接到任務後，將其拆成可平行的子任務，生出多個各自隔離的子代理，每個子代理有獨立的上下文、受限的工具集與獨立的檔案系統，執行完畢後把結果收斂回主代理，合成一份連貫輸出。技能採漸進式載入，用到才進入上下文。
它真正解決的是長程任務的兩個老問題:上下文爆炸與失憶。完成的子任務會被積極摘要、中間結果卸載到檔案系統;跨 session 的長期記憶存在本地、由你掌控,套用時會自動去除重複事實。2.0 是與 v1 完全不共用程式碼的重寫版本,v1 留在 1.x 分支;2026 年 2 月 28 日,2.0 發佈當天登上 GitHub Trending 第一名。
DeerFlow 是一個有後端、前端、沙盒的服務，需要 clone 原始碼並啟動。設定透過互動精靈完成：make setup 詢問模型供應商與沙盒模式，自動生成最小可用的 .env 與 config.yaml。執行三行指令後，在瀏覽器開啟 http://localhost:2026 即可使用。
不想在本機裝一堆相依,改走容器化開發;要多服務一起部署,則用生產模式。三種模式共用同一份 make setup 產生的設定。
.env 放 API key 與憑證，config.yaml 放模型供應商、沙盒模式、IM 頻道與追蹤設定。模型端支援 OpenAI、Anthropic Claude（走 Claude Code OAuth）、Doubao、DeepSeek、Kimi、Google Gemini（經 OpenRouter）、本地 vLLM，以及任何 OpenAI 相容 API。換模型只需修改 config.yaml。本機評估約需 4 vCPU / 8 GB RAM，生產建議 8 vCPU / 16 GB RAM。
DeerFlow 把代理能力拆成八個各司其職的子系統：技能、子代理、沙盒、記憶、上下文、模型、搜尋、頻道。每個子系統負責一類工作，組合後形成一條可自動拆任務、隔離執行、收斂輸出的流程。
.skill 壓縮包,附選用 metadata,丟進去就能擴充代理能力,不必改核心。claude-to-deerflow 技能,把 Claude Code 的能力接進 DeerFlow 流程,Anthropic 模型走 OAuth。AioSandboxProvider 把工具執行關進獨立 Docker 容器,bash、檔案操作、抓網頁都在隔離環境裡跑。LocalSandboxProvider 用每個 thread 一個主機目錄,輕量但預設關閉 bash,持久保留 uploads／workspace／outputs。/new /status /models /memory。| 你的情境 | 建議沙盒 | 關鍵取捨 |
|---|---|---|
| 要跑 bash、執行不可信程式碼 | AioSandboxProvider |
獨立 Docker 容器，完整隔離，需 Docker |
| 本機快速試、不想起容器 | LocalSandboxProvider |
每 thread 一個主機目錄,bash 預設關閉 |
| 需要保留產出、上傳檔案 | 兩者皆可 | uploads／workspace／outputs 持久保留 |
| 多服務、面向生產 | make up + AioSandboxProvider,沙盒模式在 config.yaml 設定 |
|
以下六條配置要點全部出自官方 README 與目錄結構。涵蓋初始設定、沙盒選擇、模型混搭、技能擴充、觀測接入與 IM 頻道，對應 DeerFlow 最常見的部署誤區。
別急著手刻 .env 與 config.yaml。make setup 是互動精靈,問完模型與沙盒就生出最小可用設定,跑得起來再回去調細節,比一開始就讀完整份 schema 快得多。
LocalSandboxProvider 預設停用 bash 執行以確保安全。若代理無法執行指令，請確認沙盒模式是否正確。需要 bash 執行環境，請改用 AioSandboxProvider 的 Docker 隔離模式。
除了 OpenAI、Claude、Doubao、DeepSeek、Kimi、Gemini,只要是 OpenAI 相容 API,覆寫 base_url 就能接。要省成本可混搭:主代理用強模型,子代理掛便宜或本地 vLLM。
要加自己的能力,封裝成 .skill 壓縮包(附選用 metadata)放進去即可,核心程式碼不用動。技能漸進式載入,所以多放幾個不會一次撐爆上下文。
子代理數量增加後，用肉眼追蹤錯誤效率低。LangSmith 與 Langfuse 可同時啟用，完整記錄每個子代理步驟、每次工具呼叫與 token 用量，是長程任務除錯的主要手段。
來源 · 官方 README · Observability不必每次都開 localhost:2026。接上 Telegram／Slack／Feishu／WeChat／WeCom／DingTalk 後,直接在群裡用 /new、/status、/models、/memory 操作同一個代理。
以下是一段依官方架構描述改寫的情境:你在 http://localhost:2026 丟一個含研究、運算、產出的混合任務給 DeerFlow。看主代理怎麼拆派子代理、子代理怎麼在沙盒裡跑工具、結果怎麼被摘要收斂成一份報告,並寫進跨 session 記憶。畫面為示意,實際輸出依你的模型與設定而定。
核心設計在於主代理把任務拆成三個可平行、各自隔離的子代理：研究子代理無法存取 bash，驗證子代理在 Docker 沙盒內執行，彼此上下文不互相污染。子代理完成後被摘要回收，原始內容卸載到檔案系統，這是長程任務控制上下文規模的主要機制。
最後成品落到 outputs/、結論寫進跨 session 記憶、全程可在 LangSmith 重播。這正是 harness 的意義:你維護的是任務描述與設定,不是一條手刻的 agent 流水線。
make setup、起服務。把它當基礎建設部署,不是當瀏覽器擴充。
1.x 分支,別把兩代文件混著看。
LocalSandboxProvider 預設停用 bash，需要執行指令請改用 AioSandboxProvider，該模式依賴 Docker。環境中沒有 Docker 則無法使用 Docker 隔離沙盒。
DeerFlow 的擴充點設計為開放式：加能力靠 .skill 技能包，換模型靠 config.yaml，接外部工具靠 MCP，核心程式碼大多不需修改。
1. 封裝你的 .skill。把團隊重複的工作流程做成 .skill 壓縮包(附 metadata),丟進去就成為代理的新能力。漸進式載入,放多個也不會撐爆上下文。
2. 接 MCP 外部工具。內建 MCP server 整合(支援 OAuth token 流程),把你既有的 MCP 工具接進子代理的工具集,不必為每個整合改核心。
3. 用 claude-to-deerflow 接 Claude Code。內建這個技能,把 Claude Code 的能力接進 DeerFlow 流程,Anthropic 模型走 Claude Code OAuth,不必另開一條整合。
4. 把它變成團隊入口。接上 Telegram／Slack／Feishu／WeChat／WeCom／DingTalk,讓整個團隊在 IM 裡用同一個代理,用 /models、/memory 即時切換與檢視。
5. 混搭模型省成本。在 config.yaml 讓主代理用強模型、子代理掛便宜或本地 vLLM;任何 OpenAI 相容 API 覆寫 base_url 就能接。
① README.md：完整能力清單、安裝模式、設定欄位與架構說明。
② docs/：官方文件目錄，沙盒、頻道、觀測等細節均在此處。
③ skills/public：公開技能原始碼，撰寫自訂 .skill 前建議先讀此目錄作為範本。