2026 년 2 월 28 일, DeerFlow 는 버전 2 출시 이후 GitHub Trending 에서 🏆 #1 랭크를 차지했습니다. 여러분께 무한히 감사드립니다 — 이 성취가 가능해졌습니다! 💪🔥
DeerFlow (Deep Exploration and Efficient Research Flow) 은 확장 가능한 스킬 (extensible skills) 을 기반으로 하므로 거의 모든 작업을 수행할 수 있도록 서브 에이전트, 메모리, 샌드박스를 조율하는 오픈소스 슈퍼 에이전트 허브 (super agent harness) 입니다.
deer-flow-720p.mp4
참고
DeerFlow 2.0 은 처음부터 다시 작성된 것입니다. v1 과는 코드 공유가 없습니다. 원본 Deep Research 프레임워크를 찾으시는 경우, 1.x 브랜치에서 유지 관리 중입니다 — 기여는 여전히 환영됩니다. 활동적인 개발은 2.0 으로 이동했습니다.
더 많은 정보와 실제 데모를 확인하려면 공식 웹사이트를 방문하세요.
- 우리는 DeerFlow 를 실행하기 위해 Doubao-Seed-2.0-Code, DeepSeek v3.2 와 Kimi 2.5 사용을 강력히 권장합니다
- 더 알아보기
- 중국 대륙 지역 개발자는 여기로 클릭하세요
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 가 사용 가능하면 선택하며, 사용자가 여전히 제공해야 할 누락된 설정과 함께 정확한 다음 명령어로 끝납니다.
이는 LLM 제공자, 선택적 웹 검색 및 샌드박스 모드, bash 접근, 파일 쓰기 도구와 같은 실행/안전 선호도를 선택하는 데 안내하는 인터랙티브 마법사를 실행합니다. 최소한의 config.yaml 을 생성하고 키를 .env 에 작성합니다. 약 2 분 소요됩니다. 마법사는 또한 선택적 웹 검색 제공자를 설정하거나 현재는 건너뛸 수 있습니다.
언제든 make doctor 를 실행하여 설정을 확인하고 실행 가능한 수정 힌트를 받으세요.
고급/수동 설정: 직접 config.yaml 을 편집하는 것을 선호하신다면, 전체 템플릿을 복사하기 위해 대신 다음을 실행하세요:
make config
완전한 참조를 보려면 config.example.yaml 을 확인하세요 (CLI 백엔드 제공자인 Codex CLI, Claude Code OAuth, OpenRouter, Responses API 등 포함).
수동 모델 설정 예시
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
plusbase_url
. If you prefer a provider-specific environment variable name, pointapi_key
at that variable explicitly (for exampleapi_key: $OPENROUTER_API_KEY
).To route OpenAI models through
/v1/responses
, keep usinglangchain_openai:ChatOpenAI
and setuse_responses_api: true
withoutput_version: responses/v1
.For vLLM 0.19.0, use
deerflow.models.vllm_provider:VllmChatModel
. For Qwen-style reasoning models, DeerFlow toggles reasoning withextra_body.chat_template_kwargs.enable_thinking
and preserves vLLM's non-standardreasoning
field across multi-turn tool-call conversations. Legacythinking
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 setVLLM_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
,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 asnpx -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.
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 빌드는 기본적으로 upstream uv
registry 를 사용합니다. 제한된 네트워크에서 더 빠른 미러가 필요하면 UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
와 NPM_REGISTRY=https://registry.npmmirror.com
를 make docker-init
또는 make docker-start
실행 전에 export 합니다.
Backend 프로세스는 다음 config 접근 시 자동으로 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 를 참조하세요.
Production(로컬에서 이미지를 빌드하고, 런타임 설정 및 데이터를 마운트):
make up # 이미지 빌드 및 모든 프로덕션 서비스 시작
make down # 컨테이너 중지 및 제거
접근: http://localhost:2026
상세한 Docker 개발 가이드는 CONTRIBUTING.md 를 참조하세요.
서비스를 로컬에서 실행하는 것을 선호하는 경우:
필수 조건: 위의 "Configuration" 단계를 먼저 완료 (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 에서 로컬 개발 흐름을 실행하세요. Native cmd.exe
와 PowerShell 쉘은 bash 기반 서비스 스크립트를 지원하지 않으며, WSL 은 일부 스크립트가 Git for Windows 유틸리티 (예: cygpath)
에 의존하기 때문에 보장되지 않습니다.
-
Check prerequisites: make check # Node.js 22+, pnpm, uv, nginx 확인
-
Install dependencies: make install # Backend + Frontend 의존성 및 pre-commit hooks 설치
-
(Optional) Pre-pull sandbox image: # Docker/Container 기반 샌드박스 사용 시 권장 make setup-sandbox
-
(Optional) Load sample memory data for local review: python scripts/load_memory_sample.py
이것은 샘플 fixture 를 기본 로컬 런타임 메모리 파일에 복사하여 리뷰어가 즉시 Settings > Memory 를 테스트할 수 있게 합니다. 가장 짧은 리뷰 흐름은 backend/docs/MEMORY_SETTINGS_REVIEW.md 를 참조하세요.
DeerFlow 는 Gateway API 내부에 에이전트 런타임 (agent runtime) 을 실행합니다. 개발 모드는 핫 리로드를, 프로덕션 모드는 사전 빌드된 프론트엔드를 사용합니다.
| 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 | — |
| 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 는 /api/langgraph/*
를 소유하며, nginx 뒤의 네이티브 /api/*
라우터로 이러한 공개 LangGraph 호환 경로를 변환합니다.
deploy.sh
는 빌드 및 시작을 별도로 지원합니다:
One-step (build + start)
deploy.sh
Two-step (build once, start later)
...
DeerFlow 는 여러 가지 샌드박스 실행 모드를 지원합니다:
Local Execution(호스트 머신에서 직접 샌드박스 코드를 실행)Docker Execution(isolated Docker 컨테이너에서 샌드박스 코드를 실행)Docker Execution with Kubernetes(provisioner 서비스를 통해 Kubernetes pods 에서샌드박스 코드를 실행)
Docker 개발을 위한 서비스 시작은 config.yaml sandbox 모드를 따릅니다. Local/Docker 모드에서는 provisioner 가 시작되지 않습니다.
자신의 선호 모드를 설정하려면 Sandbox Configuration Guide 를 참조하세요.
DeerFlow 는 기능을 확장하기 위해 구성 가능한 MCP 서버와 기술을 지원합니다.
HTTP/SSE MCP 서버의 경우 OAuth 토큰 플로우가 지원됩니다 (client_credentials, refresh_token).
상세한 지침은 MCP Server Guide 를 참조하세요.
DeerFlow 는 메신저 앱에서 작업을 수신할 수 있습니다. 설정된 채널은 자동으로 시작되며, 모든 채널에 대해 공개 IP 가 필요하지 않습니다.
| Channel | Transport | Difficulty |
|---|
| Telegram | Bot API (long-polling) | Easy |
| ... | | |
| config.yaml에서의 구성: | | |
channels:
langgraph_url: http://localhost:8001/api
...
Notes:
assistant_id: lead_agent 는 기본 LangGraph assistant 를 직접 호출합니다.
assistant_id 가 커스텀 에이전트 이름으로 설정되면, DeerFlow 는 여전히 lead_agent 를 통해 라우팅하며 해당 값을 agent_name 으로 주입하므로 IM 채널에서 커스텀 에이전트의 SOUL/config 가 적용됩니다.- IM 채널 워크러는 내부적으로 Gateway 의 LangGraph-compatible API 를 호출하고, 스레드 및 실행 생성에 필요한 프로세스 로컬 내부 인증과 CSRF 쿠키/헤더 쌍을 자동으로 첨부합니다.
.env 파일에서 해당 API 키를 설정하세요:
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
...
Telegram Setup
- @BotFather 와 대화하고,
/newbot 을 보내고 HTTP API 토큰을 복사하세요.
TELEGRAM_BOT_TOKEN 을 .env 에 설정하고 config.yaml 에서 채널을 활성화하세요.
Slack Setup
- api.slack.com/apps → Create New App → From scratch 에서 Slack 앱 생성하세요.
- OAuth & Permissions 아래에 Bot Token Scopes 를 추가하세요:
app_mentions:read, chat:write, im:history, im:read, im:write, files:write.
- Socket Mode를 활성화하고
connections:write 범위를 가진 앱 레벨 토큰 (xapp-…) 을 생성하세요.
- 아래에,
message.im. - SLACK_BOT_TOKEN 과 SLACK_APP_TOKEN 을 .env 에 설정하고 config.yaml 에서 채널을 활성화하세요.
Feishu / Lark Setup
- Feishu Open Platform 에서 앱을 생성하고 Bot기능을 활성화하세요.
- 권한을 추가하세요:
im:message, im:message.p2p_msg:readonly, im:resource.
- 아래에, 그리고 Long Connection모드를 선택하세요.
- 앱 ID 와 앱 시크릿을 복사하세요.
FEISHU_APP_ID 와 FEISHU_APP_SECRET 을 .env 에 설정하고 config.yaml 에서 채널을 활성화하세요.
WeChat Setup
wechat 채널을 config.yaml 에서 활성화하세요.WECHAT_BOT_TOKEN 을 .env 에 설정하거나, 첫 번째 QR 부팅을 위해 qrcode_login_enabled: true 를 설정하세요.bot_token 이 존재하지 않고 QR 부팅이 활성화되면, iLink 가 반환한 QR 콘텐츠를 모니터링하고 바인딩 플로우를 완료하세요.- QR 플로우가 성공하면 DeerFlow 는 나중에 재시작을 위해
state_dir 아래에 획득한 토큰을 저장합니다.
- Docker Compose 배포의 경우,
get_updates_buf 커서와 저장된 인증 상태를 재시작 후에도 유지하기 위해 state_dir 을 영구 볼륨에 두세요.
WeCom Setup