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.
이 번역은 AI가 원문 README를 옮긴 것입니다. 원문이 항상 우선합니다.
English | 中文 | 日本語 | Français | Русский
2026년 2월 28일, DeerFlow는 버전 2 출시 이후 GitHub Trending에서 🏆 1위를 차지했습니다. 놀라운 커뮤니티에 감사드립니다 — 여러분이 해냈습니다! 💪🔥
DeerFlow (Deep Exploration and Efficient Research Flow)는 서브 에이전트, 메모리, 샌드박스를 조율하여 거의 모든 작업을 수행할 수 있는 오픈 소스 슈퍼 에이전트 하네스입니다. 확장 가능한 스킬**로 구동됩니다.
[!NOTE]
DeerFlow 2.0은 완전히 새로 작성되었습니다. v1과 코드를 공유하지 않습니다. 원래 Deep Research 프레임워크를 찾고 있다면
1.x브랜치에서 유지 관리됩니다. 해당 브랜치에 대한 기여는 여전히 환영합니다. 활발한 개발은 2.0으로 이동했습니다.
공식 웹사이트에서 자세한 내용을 확인하고 실제 데모를 확인하세요.
DeerFlow는 BytePlus에서 독자적으로 개발한 지능형 검색 및 크롤링 도구 세트인 InfoQuest (무료 온라인 체험 지원)를 새롭게 통합했습니다.
Claude Code, Codex, Cursor, Windsurf 또는 다른 코딩 에이전트를 사용하는 경우, 한 문장으로 설정 지침을 전달할 수 있습니다:
필요하면 DeerFlow를 클론하고, https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md 를 따라 로컬 개발을 위해 부트스트랩해 줘.이 프롬프트는 코딩 에이전트를 위한 것입니다. 에이전트에게 필요시 리포지토리를 클론하고, 가능하면 Docker를 선택하고, 사용자가 제공해야 하는 다음 명령어와 누락된 설정을 정확히 알려주도록 지시합니다.
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을 참조하세요.
<details> <summary>수동 모델 설정 예시</summary>
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: trueOpenRouter 및 유사한 OpenAI 호환 게이트웨이는 langchainopenai:ChatOpenAI와 baseurl을 사용하여 구성해야 합니다. 공급자별 환경 변수 이름을 선호하는 경우 apikey를 해당 변수에 명시적으로 지정하세요(예: apikey: $OPENROUTERAPIKEY).
OpenAI 모델을 /v1/responses로 라우팅하려면 langchainopenai:ChatOpenAI를 계속 사용하고 useresponsesapi: true와 outputversion: responses/v1을 설정하세요.
vLLM 0.19.0의 경우 deerflow.models.vllmprovider:VllmChatModel을 사용하세요. Qwen 스타일 추론 모델의 경우 DeerFlow는 extrabody.chattemplatekwargs.enablethinking으로 추론을 전환하고 다중 턴 도구 호출 대화에서 vLLM의 비표준 reasoning 필드를 유지합니다. 레거시 thinking 설정은 하위 호환성을 위해 자동으로 정규화됩니다. 추론 모델은 서버를 --reasoning-parser...로 시작해야 할 수도 있습니다. 로컬 vLLM 배포가 비어 있지 않은 API 키를 허용하는 경우에도 VLLMAPI_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/auth.json을 읽습니다.CLAUDECODEOAUTHTOKEN, ANTHROPICAUTHTOKEN, CLAUDECODECREDENTIALSPATH 또는 ~/.claude/.credentials.json을 허용합니다.acp_agents.codex를 구성하는 경우 npx -y @zed-industries/codex-acp와 같은 Codex ACP 어댑터를 가리키세요. eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"API 키는 .env에 수동으로 설정하거나(권장) 셸에서 내보낼 수도 있습니다:
OPENAI_API_KEY=your-openai-api-key
TAVILY_API_KEY=your-tavily-api-key</details>
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 | 공유 사용, 다중 에이전트 실행, 보고서 생성 또는 더 무거운 샌드박스 워크로드에 권장됩니다. |
개발 (핫 리로드, 소스 마운트):
make docker-init # 샌드박스 이미지 가져오기 (한 번만 또는 이미지 업데이트 시)
make docker-start # 서비스 시작 (config.yaml에서 샌드박스 모드 자동 감지)make docker-start는 config.yaml이 프로비저너 모드를 사용하는 경우에만 provisioner를 시작합니다 (sandbox.use: deerflow.community.aiosandbox:AioSandboxProvider와 provisionerurl 사용).
Docker 빌드는 기본적으로 업스트림 uv 레지스트리를 사용합니다. 제한된 네트워크에서 더 빠른 미러가 필요한 경우 make docker-init 또는 make docker-start를 실행하기 전에 UVINDEXURL=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 # 이미지 빌드 및 모든 프로덕션 서비스 시작
make down # 컨테이너 중지 및 제거접속: http://localhost:2026
통합 nginx 엔드포인트는 기본적으로 동일 출처이며 브라우저 CORS 헤더를 내보내지 않습니다. 분할 출처 또는 포트 전달 브라우저 클라이언트를 실행하는 경우 GATEWAYCORSORIGINS를 쉼표로 구분된 정확한 출처(예: http://localhost:3000)로 설정하세요. 그러면 게이트웨이가 CORS 허용 목록과 일치하는 CSRF 출처 검사를 적용합니다.
[!IMPORTANT]
프로덕션 배포에서는
make up을 사용하세요.make docker-start는 개발용이며 프로덕션에 적합하지 않습니다.
필수 조건: Python 3.11+ 및 uv (패키지 관리자).
make dev이 명령은 가상 환경을 생성하고, 종속성을 설치하고, DeerFlow를 시작합니다. make dev는 make setup이 이미 실행되었다고 가정합니다.
make dev는 config.yaml의 sandbox.use가 deerflow.community.aio_sandbox:AioSandboxProvider로 설정된 경우에만 샌드박스 프로비저너를 시작합니다.
DeerFlow는 세 가지 샌드박스 모드를 지원합니다:
make setup 중에 선택하거나 config.yaml에서 sandbox.use: deerflow.community.docker_sandbox:DockerSandboxProvider를 설정하세요.sandbox.use: deerflow.community.local_sandbox:LocalSandboxProvider를 설정하세요. 보안 위험: 신뢰할 수 없는 입력에는 사용하지 마세요.sandbox.use: deerflow.community.aiosandbox:AioSandboxProvider를 설정하고 provisionerurl을 구성하세요.DeerFlow는 MCP(Model Context Protocol) 서버를 지원합니다. MCP 서버를 구성하려면 config.yaml에 mcp_servers 섹션을 추가하세요:
mcp_servers:
my-server:
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]DeerFlow는 IM(인스턴트 메시징) 채널을 통한 상호 작용을 지원합니다. 현재 지원되는 채널:
config.yaml에서 im.discord.enabled: true를 설정하고 봇 토큰을 구성하세요.config.yaml에서 im.telegram.enabled: true를 설정하고 봇 토큰을 구성하세요.config.yaml에서 im.slack.enabled: true를 설정하고 봇 토큰을 구성하세요.config.yaml에서 im.websocket.enabled: true를 설정하세요.LangSmith 추적을 활성화하려면 config.yaml에 다음을 추가하세요:
langsmith:
tracing: true
api_key: $LANGSMITH_API_KEY
project: deer-flowLangfuse 추적을 활성화하려면 config.yaml에 다음을 추가하세요:
langfuse:
tracing: true
public_key: $LANGFUSE_PUBLIC_KEY
secret_key: $LANGFUSE_SECRET_KEY
host: https://cloud.langfuse.comLangSmith와 Langfuse 추적을 동시에 활성화할 수 있습니다.
DeerFlow는 단순한 딥 리서치 도구에서 다양한 작업을 처리할 수 있는 완전한 슈퍼 에이전트 하네스로 발전했습니다. 핵심 아키텍처는 다음과 같습니다:
DeerFlow는 풍부한 스킬 및 도구 세트를 제공합니다:
DeerFlow는 Claude Code와 통합되어 코드 생성 및 편집 기능을 제공합니다. config.yaml에서 Claude Code를 구성하세요:
skills:
claude_code:
enabled: true
model: claude-sonnet-4-20250514DeerFlow는 작업을 전문 서브 에이전트에 위임할 수 있습니다. 서브 에이전트는 고유한 모델, 스킬 및 구성을 가질 수 있습니다. 서브 에이전트 예시:
sub_agents:
researcher:
model: gpt-4o
skills: [web_search, browser]
coder:
model: claude-sonnet-4-20250514
skills: [code_execution, bash]DeerFlow는 코드 실행을 위한 안전한 샌드박스 환경을 제공합니다. 샌드박스는 Docker 컨테이너를 사용하여 격리를 제공합니다. 파일 시스템은 샌드박스 내에서 마운트되어 에이전트가 파일을 읽고 쓸 수 있도록 합니다.
DeerFlow는 컨텍스트 엔지니어링을 사용하여 에이전트가 관련 정보를 유지하도록 합니다. 여기에는 다음이 포함됩니다:
DeerFlow는 에이전트가 세션 간에 정보를 기억할 수 있도록 장기 메모리 시스템을 포함합니다. 메모리는 벡터 데이터베이스에 저장되며 의미론적 검색을 통해 검색할 수 있습니다.
DeerFlow는 다양한 LLM을 지원합니다. 권장 모델은 다음과 같습니다:
DeerFlow는 Python 클라이언트 라이브러리를 제공하여 DeerFlow 서버와 프로그래밍 방식으로 상호 작용할 수 있습니다:
from deerflow import DeerFlow
client = DeerFlow(base_url="http://localhost:2026")
response = client.run("Python으로 피보나치 수열을 생성하는 스크립트를 작성해 줘")
print(response)DeerFlow는 터미널 사용자 인터페이스(TUI)를 제공하여 터미널에서 직접 DeerFlow와 상호 작용할 수 있습니다:
make tui전체 문서는 DeerFlow 문서에서 확인할 수 있습니다.
DeerFlow는 에이전트가 코드를 실행하고 파일 시스템에 액세스할 수 있도록 합니다. 부적절하게 배포하면 보안 위험이 발생할 수 있습니다:
기여를 환영합니다! 자세한 내용은 CONTRIBUTING.md를 참조하세요.
DeerFlow는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.
DeerFlow는 다음 오픈 소스 프로젝트의 지원을 받습니다:
DeerFlow에 기여한 모든 분들께 감사드립니다! 기여자 목록을 확인하세요.