deer-flow

KO | EN

gitlite — search

#javascript #python #hacktoberfest #typescript #llm #go #rust #docker #java #awesome #awesome-list #openai #ios #mcp

(★ 80,097)

조사, 코딩, 창작을 수행하는 오픈소스 장기(long-horizon) SuperAgent 하네스입니다. 샌드박스, 메모리, 도구, 스킬, 서브에이전트, 메시지 게이트웨이의 도움을 받아 몇 분에서 몇 시간까지 소요될 수 있는 다양한 수준의 작업을 처리합니다.

deer-flow 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 🦌 DeerFlow - 2.0

English | [中文](./README_zh.md) | [日本語](./README_ja.md) | [Français](./README_fr.md) | [Русский](./README_ru.md)

[![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](https://raw.githubusercontent.com/bytedance/deer-flow/main/backend/pyproject.toml)
[![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](https://raw.githubusercontent.com/bytedance/deer-flow/main/Makefile)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://raw.githubusercontent.com/bytedance/deer-flow/main/LICENSE)

<a href="https://trendshift.io/repositories/14699" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14699" alt="bytedance%2Fdeer-flow | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
> 2026년 2월 28일, DeerFlow는 버전 2 출시와 함께 GitHub Trending 🏆 1위에 올랐습니다. 이 모든 것을 가능하게 해주신 놀라운 커뮤니티 여러분께 진심으로 감사드립니다! 💪🔥

DeerFlow(**D**eep **E**xploration and **E**fficient **R**esearch **Flow**)는 **확장 가능한 스킬(extensible skills)**을 바탕으로 **서브 에이전트(sub-agents)**, **메모리(memory)**, 그리고 **샌드박스(sandboxes)**를 오케스트레이션하여 거의 모든 작업을 수행할 수 있는 오픈소스 **슈퍼 에이전트 하네스(super agent harness)**입니다.

https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18

> [!NOTE]
> **DeerFlow 2.0은 바닥부터 새롭게 작성되었습니다.** v1과 코드를 공유하지 않습니다. 오리지널 Deep Research 프레임워크를 찾고 계신다면 [`1.x` 브랜치](https://github.com/bytedance/deer-flow/tree/main-1.x)에서 유지보수되고 있으며, 해당 브랜치로의 기여도 여전히 환영합니다. 활성 개발은 2.0으로 이전되었습니다.

## Official Website

[**공식 웹사이트**](https://deerflow.tech)에서 더 자세한 정보와 **실제 데모**를 확인하세요.
랜딩 페이지의 케이스 스터디는 로그인 없이 허용된 읽기 전용 쇼케이스로 바로 열립니다.

## Sister Projects

- [**LLM Space**](https://github.com/deer-flow/llm-space) - DeerFlow 뒤에 숨겨진 비밀 병기를 만나보세요. 에이전트 아이디어를 프로토타이핑하고, 각 하네스 단계를 검사하고, 실패를 재플레이하고, 성능을 벤치마킹할 수 있는 단일 데스크톱 도구입니다.

## Coding Plan from ByteDance Volcengine

- DeerFlow 실행 시 Doubao-Seed-2.0-Code, DeepSeek v3.2 및 Kimi 2.5 사용을 강력히 권장합니다.
- [자세히 알아보기](https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
- [中国大陆地区的开发者请点击这里](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)

## InfoQuest

DeerFlow에는 BytePlus가 독자적으로 개발한 지능형 검색 및 크롤링 도구 세트인 [InfoQuest(온라인 무료 체험 지원)](https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest)가 새롭게 통합되었습니다.

---

## Table of Contents

- [🦌 DeerFlow - 2.0](#-deerflow---20)
  - [Official Website](#official-website)
  - [Coding Plan from ByteDance Volcengine](#coding-plan-from-bytedance-volcengine)
  - [InfoQuest](#infoquest)
  - [Table of Contents](#table-of-contents)
  - [One-Line Agent Setup](#one-line-agent-setup)
  - [Quick Start](#quick-start)
    - [Configuration](#configuration)
    - [Running the Application](#running-the-application)
      - [Deployment Sizing](#deployment-sizing)
      - [Option 1: Docker (Recommended)](#option-1-docker-recommended)
      - [Option 2: Local Development](#option-2-local-development)
    - [Advanced](#advanced)
      - [Sandbox Mode](#sandbox-mode)
      - [MCP Server](#mcp-server)
      - [IM Channels](#im-channels)
      - [LangSmith Tracing](#langsmith-tracing)
      - [Langfuse Tracing](#langfuse-tracing)
      - [Monocle Tracing](#monocle-tracing)
      - [Using Multiple Providers](#using-multiple-providers)
  - [From Deep Research to Super Agent Harness](#from-deep-research-to-super-agent-harness)
  - [Core Features](#core-features)
    - [Skills \& Tools](#skills--tools)
      - [Claude Code Integration](#claude-code-integration)
    - [Session Goals](#session-goals)
    - [Manual Context Compaction](#manual-context-compaction)
    - [Sub-Agents](#sub-agents)
    - [Sandbox \& File System](#sandbox--file-system)
    - [Context Engineering](#context-engineering)
    - [Long-Term Memory](#long-term-memory)
  - [Recommended Models](#recommended-models)
  - [Embedded Python Client](#embedded-python-client)
  - [Scheduled Tasks](#scheduled-tasks)
  - [Terminal Workbench (TUI)](#terminal-workbench-tui)
  - [Documentation](#documentation)
  - [⚠️ Security Notice](#️-security-notice)
    - [Improper Deployment May Introduce Security Risks](#improper-deployment-may-introduce-security-risks)
    - [Security Recommendations](#security-recommendations)
  - [Contributing](#contributing)
  - [License](#license)
  - [Acknowledgments](#acknowledgments)
    - [Key Contributors](#key-contributors)
  - [Star History](#star-history)

## One-Line Agent Setup

Claude Code, Codex, Cursor, Windsurf 또는 다른 코딩 에이전트를 사용하는 경우, 한 문장으로 설정 지침을 전달할 수 있습니다:

```text
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를 선택한 다음, 정확한 다음 명령어와 사용자가 제공해야 하는 누락된 설정과 함께 중단하도록 지시합니다.

## Quick Start

### Configuration

1. **DeerFlow 레포지토리 복제하기**

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

2. **설정 마법사 실행하기**

프로젝트 루트 디렉토리(`deer-flow/`)에서 다음을 실행합니다:

```bash
   make setup
   ```

그러면 LLM 제공자(provider) 선택, 선택적 웹 검색, 샌드박스 모드, bash 액세스, 파일 쓰기 도구 등 실행 및 안전 기본 설정을 안내하는 대화형 마법사가 실행됩니다. 최소한의 `config.yaml`을 생성하고 키를 `.env`에 기록합니다. 약 2분이 소요됩니다.

또한 마법사를 통해 선택적 웹 검색 제공자를 설정하거나 지금은 건너뛸 수 있습니다.

언제든지 `make doctor`를 실행하여 설정을 확인하고 실행 가능한 수정 힌트를 얻을 수 있습니다.
   로컬 설정이나 런타임 문제에 대해 GitHub 이슈를 여는 경우,
   `make support-bundle`을 실행하세요. 이 명령어는 리포터가 취해야 할 다음 단계를 출력하고,
   이슈에 붙여넣을 `*-issue-summary.md` 파일, AI 보조 이슈 작성을 위한 `*-issue-draft.md` 파일, 그리고 `.deer-flow/support-bundles/` 아래에 선택적인 증거 zip 파일을 생성합니다. AI 어시스턴트가 이슈를 작성하는 경우, 초안부터 시작하여 누락된 사실을 지어내는 대신 모든 REQUIRED 플레이스홀더를 교체하십시오. 유지보수자가 요청하거나 요약만으로는 충분하지 않은 경우에만 zip을 첨부하십시오. 유지보수자와 AI 트리아지 도구는 `triage.json`으로 시작할 수 있습니다. 번들에는 마스킹된 진단 정보와 파일 매니페스트만 포함되며, `.env`, 원본 대화 메시지 또는 사용자 파일 내용은 포함되지 않습니다.

> **고급 / 수동 설정**: `config.yaml`을 직접 편집하는 것을 선호하는 경우, 대신 `make config`를 실행하여 전체 템플릿을 복사하세요. CLI 기반 제공자(Codex CLI, Claude Code OAuth), OpenRouter, Responses API, `subagents.max_total_per_run`과 같은 서브에이전트 런타임 제한 등을 포함한 전체 참조는 `config.example.yaml`을 참조하십시오.

모델별 선택적 가격 책정은 가격이 책정된 모든 모델에서 동일한 통화를 사용해야 합니다.
   DeerFlow는 잘못된 집계 값을 제시하는 대신 통화가 혼용될 때 Console 비용 추정 기능을 비활성화합니다.

```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`).

OpenAI 모델을 `/v1/responses`를 통해 라우팅하려면 계속해서 `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` 설정은 하위 호환성을 위해 자동으로 정규화됩니다. 엔드포인트가 모든 스트리밍 청크에서 누적 사용량 스냅샷을 보고하는 경우, `cumulative_stream_usage: true`를 설정하여 DeerFlow가 해당 스냅샷을 청크별 델타로 변환하도록 하세요. 이 옵션은 기본적으로 비활성화되어 있으며 안정적인 완료 ID를 사용할 수 없는 경우 사용량을 변경하지 않습니다. 추론 모델은 서버가 `--reasoning-parser ...`와 함께 시작되어야 할 수도 있습니다. 로컬 vLLM 배포가 비어 있지 않은 API 키를 허용하는 경우에도 `VLLM_API_KEY`를 플레이스홀더 값으로 설정할 수 있습니다.

CLI 기반 제공자 예시:

```yaml
   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`를 설정하는 경우 `npx -y @zed-industries/codex-acp`와 같은 Codex ACP 어댑터를 가리키도록 하세요.
   - macOS에서는 필요한 경우 Claude Code 인증을 명시적으로 내보내십시오(export):

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

API 키는 `.env`에 수동으로 설정하거나(권장) 쉘에서 내보낼 수도 있습니다:

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

</details>

### Running the Application

#### Deployment Sizing

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 또는 메모리 사용량이 고정된 상태로 유지되는 경우, 먼저 동시 실행 수를 줄인 다음 다음 크기 단계로 이동하세요.

#### Option 1: Docker (Recommended)

**개발 환경** (핫 리로드, 소스 마운트):

```bash
make docker-init    # 샌드박스 이미지 풀 (최초 1회 또는 이미지 업데이트 시에만)
make docker-start   # 서비스 시작 (config.yaml에서 샌드박스 모드 자동 감지)
make docker-logs    # 로그 보기
```

`make docker-start`는 `config.yaml`이 프로비저너 모드(`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`을 내보내십시오.

로컬 AIO 샌드박스 제어 트래픽은 항상 직접 연결됩니다: 루프백/프라이빗 주소, 단일 레이블 클러스터 호스트, Docker/Podman 내부 호스트 이름은 `HTTP_PROXY`나 `HTTPS_PROXY`를 상속하지 않습니다. 외부 샌드박스 FQDN 및 공인 IP는 계속해서 환경 프록시 설정을 따릅니다.

백엔드 프로세스는 다음 설정 액세스 시 `config.yaml` 변경 사항을 자동으로 반영하므로, 개발 중 모델 메타데이터 업데이트 시 수동으로 재시작할 필요가 없습니다.
체크포인트 스토리지 설정인 `database.checkpoint_channel_mode` 및
`database.checkpoint_delta.snapshot_frequency`(기본값 `10`)는 예외입니다.
두 설정 모두 프로세스가 에이전트를 처음 빌드할 때(`DeerFlowClient`를 통한 경우 포함) 고정되며, 안전하게 변경하려면 프로세스를 재시작해야 합니다.

선택 사항인 `database.checkpoint_cache` 섹션(델타 채널 모드 전용)은 구체화된 체크포인트 이력을 캐시합니다. `type`은 `memory`(기본값) 또는 `redis`이며, `max_entries: 0`은 캐시를 비활성화합니다. `redis` 백엔드는 게이트웨이/비동기 전용이며, 동기화 TUI/임베디드 경로는 `memory`만 지원합니다. 이 캐시는 성능 향상 전용이며 비활성화해도 결과는 동일하므로 절대 고정되지 않으며, 하나의 체크포인트 데이터베이스를 공유하는 워커는 서로 다른 캐시 설정으로 안전하게 실행할 수 있습니다.

> [!TIP]
> Linux에서 `permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock` 오류로 Docker 기반 명령어가 실패하는 경우, 사용자를 `docker` 그룹에 추가하고 다시 로그인한 후 재시도하십시오. 전체 수정 방법은 [CONTRIBUTING.md](CONTRIBUTING.md#linux-docker-daemon-permission-denied)를 참조하세요.

**프로덕션 환경** (로컬 이미지 빌드, 런타임 설정 및 데이터 마운트):

```bash
make up     # 이미지 빌드 및 모든 프로덕션 서비스 시작
make down   # 컨테이너 중지 및 제거
```

접속: http://localhost:2026

영구 배포의 경우 `database.backend`를 `sqlite` 또는 `postgres`로 설정하세요. 선택한 백엔드는 LangGraph 체커포인터, LangGraph Store, DeerFlow 애플리케이션 데이터가 공유합니다. 지원 중단된 `checkpointer` 섹션이 있는 경우 하위 호환성을 위해 처음 두 개를 재정의(override)합니다.

통합 nginx 엔드포인트는 기본적으로 동일 출처(same-origin)이며 브라우저 CORS 헤더를 내보내지 않습니다. 분리된 출처(split-origin) 또는 포트 포워딩된 브라우저 클라이언트를 실행하는 경우, `GATEWAY_CORS_ORIGINS`를 `http://localhost:3000`과 같은 쉼표로 구분된 정확한 출처로 설정하십시오. 그러면 게이트웨이가 CORS 허용 목록 및 일치하는 CSRF 출처 검사를 적용합니다.

브라우저 로그인은 `HttpOnly` 세션 쿠키를 사용합니다. 로그인 페이지는 요청이 HTTPS(신뢰할 수 있는 `X-Forwarded-Proto: https` 포함)이거나 로컬호스트 HTTP인 경우 브라우저 세션을 연장하는 "로그인 상태 유지(keep me signed in)" 옵션을 제공합니다. 로컬호스트 예외는 직접 요청 `Host`를 사용하며 전달된 호스트 헤더를 무시합니다. 많은 임시 샌드박스 URL을 포함한 공개 HTTP 배포는 기본적으로 세션 쿠키로 대체됩니다. DeerFlow는 브라우저 스토리지에 비밀번호를 절대 저장하지 않으며, UI는 이메일 주소만 기억할 수 있습니다.

DeerFlow는 프록시 뒤에서 브라우저 대면 스킴과 출처를 복구하기 위해 여전히 `Forwarded` / `X-Forwarded-*` 헤더를 사용합니다. 번들된 nginx는 `X-Forwarded-Proto`를 설정하지만 업스트림 HTTPS 값을 보존하며 전달된 모든 헤더를 덮어쓰지 않습니다. 트래픽이 DeerFlow에 도달하기 전에 클라이언트가 제공한 포워딩 헤더를 교체하거나 제거하도록 외부 신뢰 프록시를 설정하십시오.

> [!IMPORTANT]
> 게이트웨이는 여전히 프로세스 내 활성 실행(run) 작업을 소유하므로 프로덕션 기본값은 단일 게이트웨이 워커(`GATEWAY_WORKERS=1`)입니다. 다중 워커 배포에는 Postgres, Redis 스트림 브리지(`stream_bridge.type: redis`), `run_ownership.heartbeat_enabled: true`, `run_events.backend: db`가 필요합니다. 프로세스 로컬 메모리/JSONL 이벤트 스토어는 워커 간 싱글톤 전달 영수증(delivery receipts)을 강제할 수 없습니다. 이 브리지는 워커 간에 SSE 전달 및 경계가 지정된 `Last-Event-ID` 리플레이를 공유합니다. 유효한 재연결 커서가 잘렸거나, 빈 스트림 대기를 이미 설정한 구독자가 첫 번째 전달 전에 뒤처지는 경우, 메모리 및 Redis는 부분 리플레이를 조용히 반환하는 대신 머신 리더블한 SSE `gap` 이벤트를 발생시킵니다. 웹 UI는 지속형 스레드/이벤트 상태를 다시 로드하고 유지된 테일에서 재개합니다. 임대 조정(Lease reconciliation)은 죽은 워커의 실행을 오류로 표시하고, 전달 영수증을 지속화하며, 터미널 스트림 마커를 게시하고, 유지된 스트림 정리를 예약하며, 영향을 받는 스레드 상태를 업데이트합니다. SSE 및 `/wait` 소비자도 터미널 발행에 실패할 경우의 폴백(fallback)으로 하트비트 시 지속형 상태를 새로 고칩니다. 잘못된 형식의 Redis 재연결 ID는 유지된 버퍼를 리플레이하는 대신 새 이벤트를 실시간 테일링하며, 롤링 유지 버퍼 TTL(`stream_ttl_seconds`)은 실행 타임아웃이 아니라 정리 안전망으로 유지됩니다. IM 채널 상태 및 기타 프로세스 로컬 서비스에는 여전히 자체적인 다중 워커 조정이 필요합니다.
>
> 실행 취소는 모든 게이트웨이 워커에서 발생할 수 있습니다. 소유자가 아닌 워커는 이제 라이브 소유자를 위해 인터럽트 또는 롤백 요청을 지속화하고, 소유자는 임대 갱신 중에 이를 감지하여 정상적인 취소 흐름을 수행합니다. 로드 밸런서 라우팅만으로는 더 이상 409를 생성하지 않습니다. 재시도가 소유자에 도달하더라도 먼저 허용된 작업이 승리하며, 허용된 취소는 소유자 완료와 원자적으로 경쟁합니다. 죽은 소유자는 여전히 임대 인수(takeover) 및 고아 복구를 따릅니다. 따라서 취소 지연 시간은 임대 하트비트 간격에 의해 제한됩니다.
>
> 임대 하트비트가 활성화된 경우, 일시적인 RunStore 갱신 오류는 마지막으로 확인된 임대가 만료될 때까지만 재시도됩니다. 그 후 스태일 워커는 로컬 실행을 취소하고 체크포인트, 완료 훅, 전달 영수증, 스레드 상태 최종화를 억제합니다. 이미 진행 중인 원격 도구 부수 효과는 로컬 취소 범위를 벗어날 수 있습니다.
>
> 조정은 후보 선택 후 임대를 다시 확인하는 원자적 인수 청구를 사용하므로, 성공적인 소유자 갱신이 고아 복구보다 우선하며 단 하나의 조정자만 실행을 복구됨으로 보고할 수 있습니다. 여러 게이트웨이 워커가 Docker/AIO 또는 E2B 샌드박스 백엔드를 공유하는 경우, `sandbox.ownership.type: redis`도 설정하십시오. E2B는 백그라운드 시작 및 주기적 조정 중에 임대를 사용하므로 중복/고아 정리가 라이브 피어의 샌드박스를 종료할 수 없습니다.

자세한 Docker 개발 가이드는 [CONTRIBUTING.md](CONTRIBUTING.md)를 참조하세요.

#### Option 2: Local Development

서비스를 로컬에서 실행하는 것을 선호하는 경우:

사전 요구 사항: 먼저 위의 "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에서 로컬 개발 흐름을 실행하세요. 네이티브 `cmd.exe` 및 PowerShell 쉘은 bash 기반 서비스 스크립트에서 지원되지 않으며, 일부 스크립트가 `cygpath`와 같은 Windows용 Git 유틸리티에 의존하므로 WSL도 보장되지 않습니다.

1. **사전 요구 사항 확인**:
   ```bash
   make check  # Node.js 22+, pnpm, uv, nginx 확인
   ```

로컬 `make check`, `make install`, `make dev`, `make start` 진입점은 사용 가능한 경우 직접 `pnpm`/`pnpm.cmd` 실행 파일을 사용하고, 그렇지 않으면 `corepack pnpm`으로 폴백합니다. Corepack은 `frontend/`에서 실행되므로 `frontend/package.json`에 고정된 `packageManager` 버전을 준수합니다. 글로벌 pnpm 쉼(shim)을 활성화할 필요는 없습니다.

2. **의존성 설치**:
   ```bash
   make install  # 백엔드 + 프론트엔드 의존성 + pre-commit 훅 설치
   ```

3. **(선택 사항) 샌드박스 이미지 사전 풀(Pre-pull)**:
   ```bash
   # Docker/컨테이너 기반 샌드박스를 사용하는 경우 권장
   make setup-sandbox
   ```

4. **(선택 사항) 로컬 검토를 위한 샘플 메모리 데이터 로드**:
   ```bash
   python scripts/load_memory_sample.py
   ```
   이 명령어는 검토자가 `Settings > Memory`를 즉시 테스트할 수 있도록 샘플 픽스처를 기본 로컬 런타임 메모리 파일에 복사합니다.
   가장 빠른 검토 흐름은 [backend/docs/MEMORY_SETTINGS_REVIEW.md](backend/docs/MEMORY_SETTINGS_REVIEW.md)를 참조하십시오.

5. **서비스 시작**:
   ```bash
   make dev
   ```

6. **접속**: http://localhost:2026

#### Startup Modes

DeerFlow는 게이트웨이 API 내부에서 에이전트 런타임을 실행합니다. 개발 모드는 핫 리로드를 활성화하며, 프로덕션 모드는 미리 빌드된 프론트엔드를 사용합니다.

| | **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` |

| 작업 | 로컬 | Docker Dev | Docker Prod |
|---|---|---|---|
| **중지** | `./scripts/serve.sh --stop` `make stop` | `./scripts/docker.sh stop` `make docker-stop` | `./scripts/deploy.sh down` `make down` |
| **재시작** | `./scripts/serve.sh --restart [flags]` | `./scripts/docker.sh restart` | — |

게이트웨이는 `/api/langgraph/*`를 소유하며, nginx 뒤에서 해당 공인 LangGraph 호환 경로를 네이티브 `/api/*` 라우터로 변환합니다.

LangGraph Studio 또는 직접 LangGraph Server를 통해 `backend/langgraph.json`을 호출하는 워크플로우의 경우, DeerFlow는 해당 런타임에 의해 발행된 인증된 신원을 소비하고 이를 커스텀 에이전트 설정/SOUL, 사용자 스킬 및 스킬 정책, 업로드, 스레드 데이터, 메모리 읽기/쓰기에 사용합니다. 이를 통해 인증된 실행이 공유 `default` 파일 시스템 버킷에 들어가지 않도록 유지하고, 서버 소유의 신원이 일반 클라이언트가 제공한 `user_id` 값보다 우선시됩니다. 이메일 주소와 같은 외부 신원은 DeerFlow 스토리지에 액세스하기 전에 충돌에 강하고 디렉토리에 안전한 안정적인 사용자 ID로 매핑됩니다. 기본 DeerFlow 서비스 토폴로지는 위에서 설명한 게이트웨이 임베디드 런타임으로 유지됩니다.

게이트웨이 실행은 `/mnt/user-data/outputs` 아래에서 생성 또는 수정된 아티팩트에 대해 네이티브 전달을 자동으로 강제합니다. `present_files`는 현재 실행에 의해 생성된 출력을 하나 이상 제시해야 하며, 터미널 `run.delivery` 영수증이 지속 가능하게 기록되어야 합니다. 가상 아티팩트 도로는 출력 디렉토리 경계가 검증되기 전에 출력을 생성한 동일한 인증된 사용자 및 스레드 범위 내에서 해소됩니다. 출력 아티팩트를 생성하지 않는 실행은 일반적인 대화형 동작을 유지합니다.

DeerFlow의 내장 커스텀 이벤트는 두 가지 LangGraph 스트리밍 인터페이스를 모두 통해 사용할 수 있습니다. 네이티브 클라이언트는 계속해서 `stream_mode="custom"`을 구독할 수 있으며, 콜백 기반 통합은 `astream_events(version="v2")`에서 `on_custom_event` 레코드와 동일한 페이로드를 소비할 수 있습니다. 콜백 이벤트 이름은 페이로드의 `type` 필드와 일치합니다.

#### Docker Production Deployment

`deploy.sh`는 빌드와 시작을 별도로 지원합니다:

```bash
# 원스텝 (빌드 + 시작)
deploy.sh

# 투스텝 (한 번 빌드, 나중에 시작)
deploy.sh build              # 모든 이미지 빌드
deploy.sh start              # 미리 빌드된 이미지 시작

# 중지
deploy.sh down
```

### Advanced
#### Sandbox Mode

DeerFlow는 다양한 샌드박스 실행 모드를 지원합니다:
- **로컬 실행(Local Execution)** (호스트 머신에서 샌드박스 코드를 직접 실행)
- **Docker 실행(Docker Execution)** (격리된 Docker 컨테이너에서 샌드박스 코드를 실행)
- **Kubernetes를 이용한 Docker 실행(Docker Execution with Kubernetes)** (프로비저너 서비스를 통해 Kubernetes Pod에서 샌드박스 코드를 실행)

Docker 개발의 경우, 서비스 시작은 `config.yaml` 샌드박스 모드를 따릅니다. Local/Docker 모드에서는 `provisioner`가 시작되지 않습니다.

선호하는 모드를 설정하려면 [샌드박스 설정 가이드(Sandbox Configuration Guide)](backend/docs/CONFIGURATION.md#sandbox)를 참조하세요.

#### MCP Server

DeerFlow는 기능 확장을 위해 설정 가능한 MCP 서버와 스킬을 지원합니다.
HTTP/SSE MCP 서버의 경우 OAuth 토큰 흐름(`client_credentials`, `refresh_token`)이 지원됩니다.
stdio MCP 서버의 경우 툴 호출별 타임아웃을 `tool_call_timeout`으로 설정할 수 있습니다.
서버 간 충돌을 방지하기 위해 MCP 툴 이름에는 기본적으로 `<server_name>_` 접두사가 붙습니다. 서버가 자체 툴에 이미 네임스페이스를 가지고 있는 경우, 원래 이름을 유지하기 위해 `extensions_config.json`의 해당 서버에 `tool_name_prefix: false`를 설정하십시오. 결과 이름이 활성화된 모든 서버에서 고유하게 유지되는 경우에만 접두사를 비활성화하십시오.
Settings > Tools는 한 번에 하나의 MCP 서버를 업데이트합니다. 한 서버의 잘못된 stdio 명령어가 다른 서버의 토글을 차단하지 않으며, 해당 잘못된 서버를 활성화하는 것은 여전히 명령어 허용 목록에 의해 보호되고 UI에 백엔드 검증 메시지를 표시합니다.
타겟팅된 업데이트는 SSE/HTTP 서버에 대해 DeerFlow의 `type` 필드와 MCP 규격 `transport` 필드를 모두 허용합니다.
런타임 MCP 및 스킬 업데이트는 `extensions_config.json`을 원자적으로(atomically) 교체하므로, 중단된 쓰기로 인해 공유 설정이 잘리거나 부분적으로 작성되는 일이 발생하지 않습니다.
MCP 라우팅 힌트는 다른 툴을 금지하지 않고 일치하는 요청에 대해 특정 MCP 툴을 선호할 수도 있습니다. `tool_search`가 MCP 스키마를 지연(defer)시키는 경우, 모델 호출 전에 일치하는 라우팅 메타데이터가 최대 `tool_search.auto_promote_top_k`개의 지연된 스키마를 자동으로 승격할 수 있습니다.
자세한 지침은 [MCP 서버 가이드(MCP Server Guide)](backend/docs/MCP_SERVER.md)를 참조하세요.

보안: 요청별 MCP 자격 증명은 `config.context.secrets`를 통해서만 전달하십시오.
자격 증명은 두 실행 메타데이터 표면 중 어디에도 배치되어서는 안 됩니다
(`metadata.auth_token` 또는 `config.metadata.auth_token`). 레거시 메타데이터 자격 증명에서 마이그레이션할 때 지원되는 인터셉터 흐름과 필수 로테이션 및 보관된 복사본 정리에 대해서는 [MCP 자격 증명 마이그레이션 및 정리(MCP credential migration and cleanup)](backend/docs/MCP_SERVER.md#migrating-legacy-mcp-credentials)를 참조하십시오.

#### IM Channels

DeerFlow는 메시징 앱에서 작업을 수신하는 기능을 지원합니다. 설정된 채널은 자동으로 시작되며, 공인 IP가 전혀 필요하지 않습니다.

또한 DeerFlow는 워크스페이스 UI에서 사용자가 소유한 IM 채널 연결을 노출할 수 있습니다. `channel_connections`가 활성화되면 로그인한 사용자는 사이드바 / Settings > Channels에서 Telegram, Slack, Discord, Feishu/Lark, DingTalk, WeChat, WeCom 또는 Buzz를 바인딩할 수 있습니다. 기존 아웃바운드 `channels.*` 전송을 재사용하므로 공인 IP나 제공자 콜백 URL이 필요 없습니다. 수신된 IM 메시지는 연결된 DeerFlow 사용자 계정으로 실행됩니다. 설정 및 보안 노트는 [IM 채널 연결(IM Channel Connections)](backend/docs/IM_CHANNEL_CONNECTIONS.md)을 참조하십시오.

| 채널 | 전송(Transport) | 난이도 |
|---------|-----------|------------|
| Telegram | Bot API (롱 폴링) | 쉬움 |
| Slack | Socket Mode | 보통 |
| Feishu / Lark | WebSocket | 보통 |
| WeChat | Tencent iLink (롱 폴링) | 보통 |
| WeCom | WebSocket | 보통 |
| DingTalk | Stream Push (WebSocket) | 보통 |
| Buzz | Nostr relay (WebSocket, NIP-42) | 보통 |

**`config.yaml` 설정 예시:**

```yaml
channels:
  # LangGraph 호환 게이트웨이 API 기본 URL (기본값: http://localhost:8001/api)
  langgraph_url: http://localhost:8001/api
  # 게이트웨이 API URL (기본값: http://localhost:8001)
  gateway_url: http://localhost:8001

# 선택 사항: 모든 모바일 채널에 대한 글로벌 세션 기본값
  session:
    assistant_id: lead_agent  # 또는 커스텀 에이전트 이름; 커스텀 에이전트는 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       # 중국 (기본값)
    # domain: https://open.larksuite.com   # 인터내셔널

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: []               # 비어 있음 = 모두 허용

telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    # 선택 사항: 최종 Markdown 응답을 Telegram Rich Messages로 렌더링
    rich_messages: false
    allowed_users: []               # 비어 있음 = 모두 허용

wechat:
    enabled: false
    bot_token: $WECHAT_BOT_TOKEN
    ilink_bot_id: $WECHAT_ILINK_BOT_ID
    qrcode_login_enabled: true      # 선택 사항: bot_token이 없을 때 최초 QR 부트스트랩 허용
    allowed_users: []               # 비어 있음 = 모두 허용
    polling_timeout: 35             # 타이밍 값은 양수의 유한한 초여야 함
    polling_retry_delay: 5
    qrcode_poll_interval: 2
    qrcode_poll_timeout: 180
    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

# 선택 사항: 채널별 / 사용자별 세션 설정
    session:
      assistant_id: mobile-agent  # 여기서는 커스텀 에이전트 이름도 지원됨
      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
    client_secret: $DINGTALK_CLIENT_SECRET     # 딩톡 애플리케이션의 Client Secret
    allowed_users: []                          # 비어 있음 = 모두 허용
    card_template_id: ""                       # 선택 사항: 스트리밍 타자기 효과를 위한 AI 카드 템플릿 ID
```

참고 사항:
- `assistant_id: lead_agent`는 기본 LangGraph 어시스턴트를 직접 호출합니다.
- `assistant_id`가 커스텀 에이전트 이름으로 설정된 경우, DeerFlow는 여전히 `lead_agent`를 통해 라우팅하고 해당 값을 `agent_name`으로 주입하므로 IM 채널에서도 커스텀 에이전트의 SOUL/설정이 적용됩니다.
- IM 채널 워커는 게이트웨이의 LangGraph 호환 API를 내부적으로 호출하고, 스레드 및 실행 생성을 위해 필요한 프로세스 로컬 내부 인증과 CSRF 쿠키/헤더 쌍을 자동으로 첨부합니다.
- Feishu/Lark는 이제 일반적인 바쁨(busy) 응답을 즉시 표시하는 대신 매핑된 DeerFlow `thread_id`별로 빠른 후속 메시지를 대기열에 넣으며, 토픽 응답은 대기열/실행 중/최종 패치 전반에 걸쳐 컴팩트한 소스 메시지 미리보기가 포함된 메시지별 카드를 유지합니다.

`.env` 파일에 해당 API 키를 설정하세요:

```bash
# 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 설정**

1. [@BotFather](https://t.me/BotFather)와 대화하여 `/newbot`을 전송하고 HTTP API 토큰을 복사합니다.
2. `.env`에 `TELEGRAM_BOT_TOKEN`을 설정하고 `config.yaml`에서 채널을 활성화합니다.
3. 봇은 인바운드 텍스트, 사진, 문서(캡션 유무 관계없이)를 수용합니다. 호스팅된 Bot API 다운로드는 첨부파일당 20MB로 제한됩니다.

**Slack 설정**

1. [api.slack.com/apps](https://api.slack.com/apps)에서 Slack App 생성 → Create New App → From scratch.
2. **OAuth & Permissions**에서 Bot Token Scopes 추가: `app_mentions:read`, `chat:write`, `im:history`, `im:read`, `im:write`, `files:write`.
3. **Socket Mode** 활성화 → `connections:write` 스코프가 있는 App-Level Token (`xapp-…`) 생성.
4. **Event Subscriptions**에서 봇 이벤트 구독: `app_mention`, `message.im`.
5. `.env`에 `SLACK_BOT_TOKEN` 및 `SLACK_APP_TOKEN`을 설정하고 `config.yaml`에서 채널을 활성화합니다.

**Feishu / Lark 설정**

1. [Feishu Open Platform](https://open.feishu.cn/)에서 앱 생성 → **Bot** 기능 활성화.
2. 권한 추가: `im:message`, `im:message.p2p_msg:readonly`, `im:resource`.
3. **Events**에서 `im.message.receive_v1`을 구독하고 **Long Connection** 모드를 선택합니다.
4. App ID와 App Secret을 복사합니다. `.env`에 `FEISHU_APP_ID` 및 `FEISHU_APP_SECRET`을 설정하고 `config.yaml`에서 채널을 활성화합니다.

**WeChat 설정**

1. `config.yaml`에서 `wechat` 채널을 활성화합니다.
2. `.env`에 `WECHAT_BOT_TOKEN`을 설정하거나, 최초 QR 부트스트랩을 위해 `qrcode_login_enabled: true`를 설정합니다.
3. `bot_token`이 없고 QR 부트스트랩이 활성화된 경우, iLink에서 반환된 QR 콘텐츠에 대한 백엔드 로그를 확인하고 바인딩 프로세스를 완료합니다.
4. QR 프로세스가 성공하면 DeerFlow는 이후 재시작을 위해 획득한 토큰을 `state_dir` 아래에 영구 저장합니다.
5. Docker Compose 배포의 경우, `get_updates_buf` 커서와 저장된 인증 상태가 재시작 후에도 유지되도록 `state_dir`을 영구 볼륨에 유지하십시오.

**WeCom 설정**

1. WeCom AI Bot 플랫폼에서 봇을 생성하고 `bot_id`와 `bot_secret`을 발급받습니다.
2. `config.yaml`에서 `channels.wecom`을 활성화하고 `bot_id` / `bot_secret`을 채웁니다.
3. `.env`에 `WECOM_BOT_ID` 및 `WECOM_BOT_SECRET`을 설정합니다.
4. 백엔드 의존성에 `wecom-aibot-python-sdk`가 포함되어 있는지 확인하세요. 이 채널은 WebSocket 롱 커넥션을 사용하므로 공인 콜백 URL이 필요 없습니다.
5. 현재 통합은 인바운드 텍스트, 이미지, 파일 메시지를 지원합니다. 에이전트가 생성한 최종 이미지/파일도 WeCom 대화로 다시 전송됩니다.

**DingTalk 설정**

1. [DingTalk Developer Console](https://open.dingtalk.com/)에서 DingTalk 애플리케이션을 생성하고 **Robot** 기능을 활성화합니다.
2. 봇 설정 페이지에서 메시지 수신 모드를 **Stream Mode**로 설정합니다.
3. `Client ID`와 `Client Secret`을 복사하고, `.env`에 `DINGTALK_CLIENT_ID` 및 `DINGTALK_CLIENT_SECRET`을 설정한 뒤, `config.yaml`에서 채널을 활성화합니다.
4. *(선택 사항)* 스트리밍 AI 카드 응답(타자기 효과)을 활성화하려면 [DingTalk Card Platform](https://open.dingtalk.com/document/dingstart/typewriter-effect-streaming-ai-card)에서 **AI Card** 템플릿을 생성한 후 `config.yaml`의 `card_template_id`를 해당 템플릿 ID로 설정하십시오. 또한 `Card.Streaming.Write` 및 `Card.Instance.Write` 권한을 신청해야 합니다.

DeerFlow가 Docker Compose에서 실행될 때 IM 채널은 `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`을 설정하세요.

**명령어**

채널이 연결되면 채팅에서 직접 DeerFlow와 상호작용할 수 있습니다:

| 명령어 | 설명 |
|---------|-------------|
| `/new` | 새 대화 시작 |
| `/status` | 현재 스레드 정보 표시 |
| `/models` | 사용 가능한 모델 나열 |
| `/memory` | 메모리 보기 |
| `/help` | 도움말 표시 |

> 명령어 접두사가 없는 메시지는 일반 채팅으로 처리됩니다. DeerFlow는 스레드를 생성하고 대화 형식으로 응답합니다.

#### Request Trace Correlation

게이트웨이 요청 추적 상관관계(request trace correlation)는 기존 HTTP 응답과 로그 형식이 변경되지 않도록 기본적으로 비활성화되어 있습니다. 이를 활성화하려면 다음과 같이 설정하십시오:

```yaml
logging:
  enhance:
    enabled: true
    format: text
```

활성화되면 모든 게이트웨이 HTTP 응답에는 `X-Trace-Id`가 포함되고, 로그에는 `trace_id`가 포함되며, 해당 요청에 의해 생성된 Langfuse 트레이스에는 동일한 값을 가진 `metadata.deerflow_trace_id`가 포함됩니다.

또한 게이트웨이 실행 기록은 0개 출력 및 크래시 복구 실행을 포함하여 실행당 하나의 터미널 `run.delivery` 영수증을 기록합니다. 영수증은 일반 실행 중 내구성 있는 터미널 실행 상태 전에 지속됩니다. 고아 복구는 만료된 임대를 원자적으로 청구한 후 영수증을 멱등성 있게 백필하므로, 스태일 복구 스캔이 라이브 실행의 상세한 전달 사실을 덮어쓸 수 없습니다. 이벤트 스토어 중단 중에도 영수증 지속화는 베스트 에포트(best-effort)로 유지됩니다. 체크포인트 사전 검사에 실패하거나(또는 이전 최종화를 기다리는 동안 취소된) 실행은 기존 완료 데이터 동작을 유지합니다. 즉, 0-delivery 영수증을 받지만 빈 스냅샷으로 RunStore 완료 필드를 덮어쓰지 않습니다.

#### LangSmith Tracing

DeerFlow에는 관측 가능성(observability)을 위해 [LangSmith](https://smith.langchain.com) 통합이 내장되어 있습니다. 활성화되면 모든 LLM 호출, 에이전트 실행 및 툴 실행이 추적되어 LangSmith 대시보드에 표시됩니다.

`.env` 파일에 다음을 추가하세요:

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

#### Langfuse Tracing

DeerFlow는 LangChain 호환 실행을 위한 [Langfuse](https://langfuse.com) 관측 가능성도 지원합니다.

`.env` 파일에 다음을 추가하세요:

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

자체 호스팅(self-hosted) Langfuse 인스턴스를 사용하는 경우 `LANGFUSE_BASE_URL`을 배포 URL로 설정하세요.

**추적 상관관계 필드(Trace correlation fields).** 모든 에이전트 실행에는 Langfuse의 예약된 트레이스 속성이 주석으로 추가되어 Sessions 및 Users 페이지가 자동으로 활성화됩니다:

- `session_id` = LangGraph `thread_id` — 동일한 대화의 모든 트레이스 그룹화
- `user_id` = `get_effective_user_id()`의 유효 사용자 (인증 없음 모드에서는 `default`로 폴백)
- `trace_name` = 어시스턴트 ID (기본값 `lead-agent`)
- `tags` = `[env:<DEER_FLOW_ENV>, model:<model_name>]` (설정되지 않은 경우 생략)
- `metadata.deerflow_trace_id` = DeerFlow 요청 상관관계 ID, 요청 추적 상관관계가 활성화된 경우 `X-Trace-Id`와 일치

이들은 게이트웨이 경로(`runtime/runs/worker.py::run_agent`)와 임베디드 경로(`client.py::DeerFlowClient.stream`) 모두에 대해 그래프 호출 루트에서 `RunnableConfig.metadata`에 주입되므로 모든 LangChain 호환 콜백이 이를 읽을 수 있습니다. 배포 환경별로 트레이스에 태그를 지정하려면 `DEER_FLOW_ENV`(또는 `ENVIRONMENT`)를 설정하십시오.

#### Monocle Tracing

DeerFlow는 에이전트 애플리케이션을 위한 OpenTelemetry 기반 트레이서인 [Monocle](https://github.com/monocle2ai/monocle)도 지원합니다. LLM 호출, 에이전트 단계, 툴 및 MCP 호출 등 각 실행을 입력, 출력, 타이밍, 토큰 수와 함께 엔드투엔드로 기록합니다.

`.env` 파일에 다음을 추가하세요:

```bash
MONOCLE_TRACING=true
MONOCLE_EXPORTERS=file          # file, console, okahu, s3, blob, gcs (기본값: file)
OKAHU_API_KEY=okh_xxxxxxxx      # `okahu` 익스포터에만 필수
```

각 실행은 `.monocle/`에 하나의 트레이스 파일을 기록합니다. [Monocle VS Code 확장프로그램](https://marketplace.visualstudio.com/items?itemName=OkahuAI.monocle-apptrace)에서 이를 열어 스팬 타임라인과 토큰 수를 검사할 수 있습니다. 실행 전반에 걸쳐 트레이스를 분석하고 트레이스 기반 및 에이전트 평가를 실행하기 위해(`okahu` 익스포터를 통해) 에이전트 관측 플랫폼인 [Okahu](https://www.okahu.ai)에 연결하세요.

트레이스는 프롬프트, 툴 인수, 모델 응답과 같은 스팬 입력과 출력을 그대로 캡처하며 토큰 사용량과 타이밍도 함께 기록합니다. `file` 익스포터는 이를 로컬 디스크에 유지하며 회전(rotate)하거나 정리하지 않으므로 주기적으로 `.monocle/`을 정리하십시오. 원격 익스포터(`okahu`, `s3`, `blob`, `gcs`)는 동일한 데이터를 외부로 전송하므로 신뢰할 수 있는 대상만 활성화하십시오. Monocle은 게이트웨이 시작 시 한 번 초기화됩니다. 설정 오류(알 수 없는 익스포터, 누락된 `OKAHU_API_KEY`)가 발생하면 그곳에 로깅되고 게이트웨이가 재시작될 때까지 추적이 꺼진 상태로 유지됩니다.

#### Using Multiple Providers

LangSmith와 Langfuse는 LangChain 콜백으로 연결되므로 둘 다 활성화하면 DeerFlow가 각 실행을 양쪽 모두에 보고합니다. 활성화된 제공자에 필수 자격 증명이 누락되었거나 초기화에 실패하면 DeerFlow는 빠르게 실패하고 해당 제공자 이름을 지정합니다. Monocle은 콜백 대신 글로벌 OpenTelemetry 제공자를 사용하며, Langfuse도 해당 제공자를 공유하므로 세 가지 모두 함께 실행될 수 있습니다. 두 스팬 프로세서가 동일한 공유 제공자에 위치하므로 둘 다 활성화된 경우 Monocle의 익스포터도 Langfuse의 스팬을 볼 수 있습니다.

Docker 배포의 경우 추적이 기본적으로 비활성화되어 있습니다. 활성화하려면 `.env`에 `LANGSMITH_TRACING=true` 및 `LANGSMITH_API_KEY`를 설정하세요.

## From Deep Research to Super Agent Harness

DeerFlow는 Deep Research 프레임워크로 시작되었으며 커뮤니티가 이를 발전시켰습니다. 출시 이래 개발자들은 데이터 파이프라인 구축, 슬라이드 데크 생성, 대시보드 스핀업, 콘텐츠 워크플로우 자동화 등 연구를 넘어선 영역으로 이를 확장했습니다. 우리가 전혀 예상하지 못했던 일들이었습니다.

이는 우리에게 중요한 사실을 말해주었습니다. DeerFlow는 단순한 연구 도구가 아니었습니다. 그것은 **하네스(harness)**, 즉 에이전트가 실제로 일을 완료할 수 있는 인프라를 제공하는 런타임이었습니다.

그래서 우리는 바닥부터 다시 만들었습니다.

DeerFlow 2.0은 더 이상 이리저리 엮어야 하는 프레임워크가 아닙니다. 배터리가 기본 내장되어 있고 완전히 확장 가능한 슈퍼 에이전트 하네스입니다. LangGraph와 LangChain을 기반으로 구축되었으며 파일 시스템, 메모리, 스킬, 샌드박스 인식 실행, 복잡한 다단계 작업을 위한 계획 및 서브 에이전트 생성 능력을 비롯해 에이전트에 필요한 모든 것을 기본 제공합니다.

있는 그대로 사용하거나, 해체하여 여러분의 것으로 만드세요.

## Core Features

### Skills & Tools

스킬은 DeerFlow가 *거의 모든 것*을 수행할 수 있게 만드는 요소입니다.

표준 에이전트 스킬은 워크플로우, 모범 사례, 지원 리소스에 대한 참조를 정의하는 마크다운 파일인 구조화된 기능 모듈입니다. DeerFlow에는 연구, 리포트 생성, 슬라이드 제작, 웹 페이지, 이미지 및 영상 생성 등을 위한 내장 스킬이 함께 제공됩니다. 그러나 진정한 강점은 확장성에 있습니다. 나만의 스킬을 추가하고, 내장 스킬을 교체하거나, 이를 복합 워크플로우로 결합할 수 있습니다.

스킬은 한 번에 모두 로드되는 것이 아니라 작업에 필요할 때 점진적으로 로드됩니다. 이를 통해 컨텍스트 윈도우를 간결하게 유지하고 토큰에 민감한 모델에서도 DeerFlow가 잘 작동하도록 만듭니다.

스킬 디렉토리는 패키지 경계입니다. DeerFlow가 `SKILL.md`를 찾으면, 해당 패키지 아래의 중첩된 `SKILL.md` 파일(예: 평가 픽스처)은 지원 데이터로 유지되며 런타임 스킬로 등록되지 않습니다. 자체 `SKILL.md`가 없는 네임스페이스 디렉토리는 중첩된 스킬들을 계속 그룹화할 수 있습니다.

사용자는 요청을 `/skill-name`(예: `/data-analysis analyze uploads/foo.csv`)으로 시작하여 단일 턴 동안 활성화된 스킬을 명시적으로 활성화할 수 있습니다. DeerFlow는 기본 프롬프트를 스킬 메타데이터로 제한한 상태에서 해당 스킬의 `SKILL.md`를 숨겨진 현재 턴 컨텍스트로 로드합니다. 슬래시 활성화는 비활성화된 스킬, 커스텀 에이전트 스킬 화이트리스트, `/new` 및 `/help`와 같은 기존 채널 명령어를 존중합니다.

활성화된 스킬의 `allowed-tools` 정책은 해당 스킬이 슬래시 활성화되거나 `read_file` 로드 후 에이전트의 활성 스킬 컨텍스트에 캡처된 후에만 적용됩니다. 커스텀 에이전트 또는 서브에이전트 `skills` 허용 목록에서 스킬을 단순히 활성화, 광고 또는 나열하는 것은 해당 에이전트의 일반적인 툴셋을 줄이지 않으며, 서브에이전트는 리드 에이전트와 동일한 점진적 검색 및 활성화 정책을 사용합니다. 슬래시 활성화된 실행 중에는 해당 명시적 스킬의 정책이 권위(authoritative)를 가집니다. 다른 `SKILL.md`를 읽는 것은 지침을 제공할 수 있지만 슬래시 스킬의 툴을 넓힐 수는 없습니다. 슬래시 활성화가 없으면 활성 컨텍스트에 실제로 로드된 스킬의 정책은 합집합(union) 의미론을 유지합니다. 활성화되면 정책은 모델에 보이는 툴 스키마와 툴 실행 모두를 필터링합니다. 프레임워크 검색 툴(`tool_search` 및 `describe_skill`)은 허용된 지연(deferred) 툴이나 설치된 스킬을 계속 검색할 수 있도록 유지되지만, 검색 및 승격은 `allowed-tools`에서 누락된 비즈니스 툴을 실행할 권한을 부여하지 않습니다. `task`는 프레임워크 면제 대상이 아닙니다. 제한적인 스킬은 서브에이전트에 위임하기 위해 이를 명시적으로 나열해야 합니다. 단계별 정책 결정은 내부 런타임 컨텍스트이며 관찰 가능하거나 지속된 컨텍스트 복사본에서 제거됩니다. 레지스트리 실패 및 남은 유효한 스킬이 없는 활성 세트는 프레임워크 안전 툴로 닫힌 상태로 실패(fail closed)합니다. 개별 스태일 경로는 다른 유효한 활성 스킬이 남아 있는 경우에만 무시됩니다. 이는 엄격한 보안 경계가 아닌 베스트 에포트 동작 범위 지정(behavioral scoping)입니다. 다른 툴을 통해 스킬 지침을 로드하는 것은 캡처되지 않으며, 활성 스킬 항목은 경계가 지정된 컨텍스트에서 축출될 수 있습니다.

게이트웨이를 통해 `.skill` 아카이브를 설치할 때, DeerFlow는 그렇지 않으면 유효한 외부 스킬을 거부하는 대신 `version`, `author`, `compatibility`와 같은 표준 선택적 프런트매터 메타데이터를 허용합니다.

스킬을 비활성화하면 샌드박스 파일 시스템 뷰에서도 제거되므로 쉘 명령어와 구조화된 파일 툴이 동일한 활성화 상태를 따릅니다. 로컬, Docker/AIO, hostPath 프로비저너, 그리고 새로 생성된 E2B 샌드박스는 공개, 커스텀, 레거시 또는 관리형 통합 스킬이 토글, 편집, 생성, 삭제 또는 설치될 때 업데이트되는 활성화 전용 프로젝션에서 `/mnt/skills`를 소싱합니다. 관리형 통합 패키지는 공유 상태로 유지되는 반면, 프로젝션된 파일 시스템 가시성은 각 사용자의 활성화 상태를 따릅니다. 다중 워커 게이트웨이는 사용자 프로젝션을 재구축하는 동안 디스크의 활성화 상태를 다시 읽으므로, 한 워커가 처리한 토글은 다른 워커의 다음 샌드박스 획득 시 반영됩니다. 기존 E2B 샌드박스는 재생성될 때까지 생성 시점의 스냅샷을 유지합니다. PVC 백엔드 프로비저너 스킬은 현재로서는 구성된 PVC 스냅샷/레이아웃을 유지하며, 동적 PVC 구체화는 별도로 추적됩니다.

관리형 통합은 커스텀 스킬과 혼합하지 않고 공유 읽기 전용 스킬 팩을 설치합니다. Lark/Feishu CLI 통합은 `Settings → Integrations → Lark / Feishu CLI`에서 사용할 수 있습니다. 관리자는 `{DEER_FLOW_HOME}/integrations/skills/lark-cli` 아래에 공식 `lark-*` 팩을 한 번 설치 또는 업그레이드하며, 모든 사용자는 독립된 활성화 상태로 동일한 팩을 검색합니다. 각 사용자의 앱 설정 및 OAuth 데이터는 `{DEER_FLOW_HOME}/users/{user_id}/integrations/lark-cli/{config,data}` 아래에 격리된 상태로 유지됩니다. 이러한 비밀 디렉토리는 `0700`으로 제한되고, 일반 자격 증명 파일은 `0600`으로 제한되며, 심볼릭 링크는 거부됩니다.

설치 후 사용자는 **Connect Lark**를 클릭하여 브라우저 승인 링크를 열 수 있으며 터미널 승인이 필요 없습니다. 동일한 UI를 통해 캘린더, 문서, 드라이브와 같은 추가 권한 영역이나 `lark-cli`가 보고하는 특정 OAuth 스코프를 요청할 수 있습니다. 저렴한 상태 새로 고침은 로컬 자격 증명 트리만 검사하므로, 명시적인 브라우저 완료가 라이브 토큰 검증을 수행할 때까지 UI는 **Credentials configured (not live-verified)**를 보고합니다. 그 후 작업은 **Reconnect Lark**로 유지되므로 사용자가 승인을 교체하거나 확장할 수 있습니다. 대화 도중 에이전트에 Lark 승인이 누락된 경우 관리형 `lark-shared` 가이던스는 사용자를 `?settings=integrations`가 포함된 동일한 설정 항목으로 다시 안내합니다.

Lark 스킬 팩을 설치하면 GitHub에서 최신 공식 `larksuite/cli` 릴리스를 해결하고 설치 시점에 해당 버전의 스킬을 다운로드하므로 게이트웨이에 해당 단계를 위한 아웃바운드 인터넷 액세스가 필요합니다(릴리스 조회에 실패하면 최하단 고정 버전으로 폴백합니다). 설정 페이지에는 설치된 버전과 (가능한 경우) 가장 최근에 게시된 버전이 표시되므로 관리자가 재설치하여 업그레이드할 수 있습니다. 에어갭(air-gapped) 배포의 경우 아카이브를 미리 스테이징하고 `DEER_FLOW_LARK_CLI_SKILLS_ARCHIVE`가 로컬 파일을 가리키도록 할 수 있습니다. 무결성은 고정된 아카이브 바이트 해시에 의존하지 않습니다(GitHub은 안정적인 소스 아카이브 바이트를 보장하지 않음). 대신 다운로드가 공식 GitHub 호스트로 제한되고, 모든 아카이브 멤버가 구조적 안전 보호를 통과하며, (DeerFlow가 주입한 공유 가이던스를 포함한) 효과적으로 설치된 스킬 트리의 콘텐츠 해시가 기록되어 재설치 전반에 걸쳐 콘텐츠 변경 사항을 감사할 수 있습니다.

`sandbox.use`가 AIO 제공자를 선택하는 경우, 동일한 설치를 통해 공식 Linux amd64 및 arm64 CLI 릴리스 아카이브도 다운로드하고, 게시된 SHA-256 체크섬을 검증하며, 아키텍처당 하나의 실행 파일을 안전하게 추출하고, 결과 런타임을 `/mnt/integrations/lark-cli/runtime`에 읽기 전용으로 마운트합니다. 해당 마운트의 아키텍처 선택 런처는 샌드박스 `PATH`에서 `lark-cli`를 사용할 수 있게 만듭니다. 에어갭 AIO 배포는 `bin/lark-cli`와 `linux-{amd64,arm64}/lark-cli` 파일이 모두 포함된 심볼릭 링크가 없는 런타임 트리를 미리 스테이징하고 `DEER_FLOW_LARK_CLI_SANDBOX_RUNTIME_DIR`를 해당 디렉토리로 설정할 수 있습니다.

> **샌드박스 신뢰 경계:** 브라우저는 Lark 앱 비밀키를 절대 받지 않지만 에이전트 대화는 샌드박스 내에서 `lark-cli`를 실행하므로 사용자별 자격 증명 디렉토리가 샌드박스에 마운트됩니다. (수명이 긴 `appSecret`을 보유한) `config`는 **읽기 전용**으로, (새로 고칠 수 있는 OAuth 토큰인) `data`는 쓰기 가능으로 마운트됩니다. 둘 다 에이전트가 그곳에서 실행하는 모든 프로세스에 의해 여전히 *읽을 수* 있으므로 툴 결과의 프롬프트 주입을 통해 도달한 코드가 이를 읽을 수 있습니다. 사이드카 자격 증명 브로커 후속 조치가 샌드박스 실행에서 이러한 마운트를 제거할 때까지 샌드박스를 Lark 자격 증명 신뢰 경계 내에 있는 것으로 취급하십시오.

원격/Kubernetes 배포(프로비저너 백엔드)의 경우, 샌드박스 `lark-cli` 런타임은 바이너리를 공유 `emptyDir`에 복사하는 선택적 init 컨테이너에 의해 제공될 수 있습니다. 설치 시점의 GitHub 다운로드나 hostPath/PVC 런타임 마운트가 없습니다. [`docker/lark-cli-init`](docker/lark-cli-init/README.md) 아래에 이미지를 게시하고 프로비저너에 `LARK_CLI_INIT_IMAGE`를 설정하십시오. 설정되지 않은 경우 꺼진 상태로 유지됩니다(레거시 동작). Lark 통합 상태(`GET /api/integrations/lark/status`)는 `sandbox_runtime_mode` 및 `sandbox_runtime_ready`를 보고하므로 설정 UI는 나중에 `command not found`를 숨기는 녹색 상태 대신 `lark-cli`가 채팅 시점에 샌드박스에 실제로 존재할지 여부를 표시합니다.

신뢰할 수 있는 운영자가 MinIO, NFS 또는 CSI와 같은 외부 마운트를 통해 구성된 스킬 디렉토리를 관리하는 경우, 관리자는 파일을 변경한 후 `POST /api/skills/reload`를 호출할 수 있습니다. 이는 현재 게이트웨이 프로세스의 스킬 프롬프트 캐시를 무효화하고 바운드된 새로 고침 타임아웃까지 대기하므로 후속 실행이 최신 파일을 다시 스캔하게 됩니다. 실행 중인 작업은 변경되지 않습니다. 로더 수준의 파일 시스템 오류는 일반적인 서버 오류를 반환하고 빈 카탈로그를 발행하는 대신 마지막으로 성공적으로 로드된 프로세스 캐시를 유지합니다. Uvicorn 워커와 Kubernetes Pod는 각각 별도로 타겟팅되어야 합니다. 직접 마운트 쓰기는 DeerFlow의 설치/편집 API에 의해 적용되는 검증, SkillScan 및 이력을 우회하므로 운영자 제어 시스템에만 쓰기 권한이 있어야 합니다.

스킬 설치 및 에이전트 관리 스킬 편집은 LLM 기반 스킬 스캐너 이전의 네이티브 결정론적 안전 스캐너인 **SkillScan**을 거칩니다. Phase 1은 Semgrep/OpenGrep 종속성 없이 오프라인으로 실행되며, 개인키 또는 쉘 실행과 같은 높은 신뢰도의 `CRITICAL` 발견 항목을 차단하고 경고 발견 항목을 문맥 검토를 위해 LLM 스캐너로 전달합니다. Python 인스턴스 클라이언트 유출 검사는 간단한 이름이 알려진 클라이언트 생성자에 바인딩된 경우, 선택적 이름 간 별칭, 해당 생성자가 지원하는 실제 아웃바운드 메서드 또는 컨텍스트 관리자 사용과 같은 최소한의 동일 범위 증거 체인을 따릅니다. 생성자 루트는 증명된 임포트여야 하며, 단순한 표준형 이름은 모듈로 유추되지 않습니다. 중첩된 경계(scopes)는 클라이언트 핸들을 상속하지 않으며 enclosing 범위에서 절대 재바인딩되지 않는 생성자 임포트 별칭만 상속합니다. 컴프리헨션, 왈러스(walrus) 연산이 포함된 문장, 어노테이션, 복잡한 바인딩 타겟, 지원되지 않는 연산 및 모호한 분기 흐름은 이 시그널에서 발견 항목을 생성하지 않습니다. 건너뛴 구문은 유효하지 않은 클라이언트 상태가 발견 항목을 생성하지 않도록 바인딩할 수 있는 모든 이름을 보수적으로 무효화합니다. 이 베스트 에포트 분석에 도달한 결정론적 작업 예산 또는 재귀 제한은 파일에 대해 이미 수집된 발견 항목을 폐기하지 않습니다. 결정론적 analyzer만 비활성화하려면 `config.yaml`에서 `skill_scan.enabled: false`를 설정하십시오. 안전한 아카이브 추출 및 LLM 스캐너는 계속 실행됩니다.

또한 DeerFlow에는 읽기 전용 스킬 품질 검토를 위한 공개 스킬인 **skill-reviewer**가 함께 제공됩니다. 대상 스킬을 활성화하거나, 비밀을 바인딩하거나, 스크립트를 실행하거나, 설치하지 않고도 내장된 `review_skill_package` 툴을 사용하여 설치된 스킬, 로컬 패키지, 아카이브 또는 붙여넣은 `SKILL.md` 콘텐츠를 검사합니다. 이 툴은 모델 컨텍스트에 컴팩트하고 태그가 중화된 JSON 페이로드를 반환하고 프로그래밍 방식 소비자를 위해 전체 원시 검토 페이로드를 툴 아티팩트에 보관합니다. 결정론적 검토 코어는 DeerFlow 파싱 및 SkillScan 팩트를 재사용하고, `contracts/skill_review/` 아래에 버전화된 JSON 계약을 발행하며, 백엔드 CLI에서 실행할 수 있습니다:

```bash
cd backend
uv run python -m deerflow.skills.review.cli ../skills/public/data-analysis --format text --fail-on error --fail-on-incomplete
```

툴도 이와 동일한 철학을 따릅니다. DeerFlow에는 웹 검색, 웹 페치, 렌더링된 웹 캡처, 파일 작업, bash 실행과 같은 핵심 툴셋이 포함되어 있으며, MCP 서버와 Python 함수를 통한 커스텀 툴을 지원합니다. 무엇이든 교체하고 무엇이든 추가하세요.

고급 배포에서는 `config.yaml`의 `authorization.enabled`를 통해 플러그인 가능한 권한 부여를 활성화할 수 있습니다. 설정된 `AuthorizationProvider`는 모델이나 지연된 툴 카탈로그에 도달하기 전에 거부된 툴을 필터링한 다음, 기존 가드레일 미들웨어를 통해 모든 비즈니스 툴 실행 전에 동일한 제공자를 다시 확인합니다. 게이트웨이 `threads:*` 및 `runs:*` 경로 권한은 동일한 제공자에서 파생되며, 기존 소유자 검사 및 관리자 전용 관리 게이트는 계속 유효합니다. 생성된 `tool_search`는 이미 필터링된 현재 빌드의 지연된 카탈로그를 앞설 때만 두 번째 툴 검사를 우회할 수 있습니다. 내장 RBAC 제공자는 역할별 `tools` 및 `routes` 허용/거부 정책을 지원하며 `default_role`이 설정된 역할을 명명하는지 검증합니다. 권한 부여는 기본적으로 비활성화되어 있습니다. `config.example.yaml` 및 [권한 부여 RFC(authorization RFC)](docs/plans/2026-07-10-pluggable-authorization-rfc.md)를 참조하십시오.

고급 배포는 `config.yaml` 또는 `extensions_config.json`의 `extensions.middlewares` 아래에 인자 없는 `AgentMiddleware` 클래스를 선언하여 에이전트 런타임 자체를 확장할 수도 있습니다. DeerFlow는 내장 런타임 미들웨어 및 루프/토큰 보호기 이후, 그러나 터미널 응답/안전/명확화(clarification) 테일 이전의 리드 에이전트 및 서브에이전트 파이프라인에 동일한 설정된 클래스 목록을 로드하므로, 엔터프라이즈 포크는 내장 미들웨어 빌더를 패치하지 않고도 도메인 가드레일, 툴 호출 거버넌스 또는 관측 가능성 훅을 추가할 수 있습니다. 누락된 패키지, 잘못된 클래스, 손상된 모듈은 에이전트 생성 시 크게(loudly) 실패합니다. `config.yaml` 및 `extensions_config.json`을 신뢰할 수 있는 운영자 제어 파일로 취급하십시오. 미들웨어 도로는 커스텀 툴, 모델, 샌드박스, 가드레일, MCP 서버 및 MCP 인터셉터 선언과 마찬가지로 코드 실행입니다. 게이트웨이 스킬/MCP 토글 엔드포인트는 이 필드를 보존하지만 `extensions_config.json`에 대한 API 쓰기 경로는 노출하지 않습니다. 컨텍스트별 파라미터화와 리드 전용/서브에이전트 전용 미들웨어 목록은 아직 지원되지 않습니다.

패키지화되고 설정 가능한 미들웨어 통합을 위해 `config.yaml`의 최상위 `plugins:` 목록을 사용하십시오. 플러그인은 `module.path:install`을 노출하고 독립형 `deerflow-extension-api` 계약 패키지에만 의존하며, DeerFlow의 빌더를 패치하지 않고도 격리된 미들웨어를 시맨틱 리드/서브에이전트 모델 또는 툴 위치에 기여할 수 있습니다. 플러그인 순서는 결정론적이고 플러그인별 설정이 `install()`에 전달되며, `required: true`는 로드 실패 시 시작을 중단시키고, 그렇지 않으면 실패가 보고되고 건너뜁니다. 플러그인은 게이트웨이 앱이 구성될 때 한 번 로드되므로 변경하려면 재시작이 필요합니다. Python 코드를 임포트하기 때문에 `plugins:`는 API로 쓰기 가능한 `extensions_config.json`을 통해 의도적으로 사용할 수 없습니다. Docker 배포의 경우 호스트 환경뿐만 아니라 게이트웨이 이미지에도 플러그인을 설치하십시오. 설정은 `config.example.yaml`을 참조하십시오.

게이트웨이에서 생성된 후속 제안은 이제 JSON 배열 응답을 파싱하기 전에 일반 문자열 모델 출력과 블록/목록 스타일의 리치 콘텐츠를 모두 정규화하므로, 제공자 전용 콘텐츠 wrapper가 제안을 조용히 드롭하지 않습니다.

웹 UI 컴포저는 전송하기 전에 초안 입력을 다듬을 수 있습니다. 리라이트는 `input_polish` 모델 설정을 사용하는 짧은 게이트웨이 LLM 요청으로 실행되며, `/data-analysis`와 같은 슬래시 스킬 접두사를 유지하고, 사용자가 다듬기 버튼을 클릭한 후에만 로컬 초안을 교체합니다. 스레드 실행을 생성하거나 메시지를 지속화하지 않습니다.

에이전트가 명확화를 요청하면 웹 UI는 구조화된 응답 카드를 표시하지만 일반 컴포저는 계속 사용할 수 있습니다. 사용자는 카드를 완성하거나 자유 형식의 채팅 메시지를 보내 이를 우회할 수 있습니다. 해당 메시지는 가장 최근의 대기 중인 명확화를 닫고 에이전트의 다음 입력이 됩니다.

전송되지 않은 웹 UI 컴포저 초안은 페이지 새로 고침 및 동일한 브라우저 탭 내 대화 간 전환 시에도 유지됩니다. 초안은 사용자, 에이전트, 대화별로 격리되며, 존재하는 경우 선택된 슬래시 스킬을 포함하고, 전송이 수락되면 지워집니다. 첨부파일과 인용된 대화 컨텍스트는 의도적으로 지속되지 않습니다.

또한 웹 UI 컴포저는 브라우저가 Web Speech API를 노출할 때 브라우저 기반 음성 받아쓰기를 지원합니다. 마이크 버튼은 음성을 로컬 초안으로만 변환하며, DeerFlow는 변환된 텍스트만 수신하고 오디오 처리는 해당 환경의 정책에 따라 브라우저 또는 운영 체제의 음성 인식 서비스에 위임됩니다. 사용자는 전송하기 전에 텍스트를 검토하거나 편집할 수 있습니다.

웹 UI는 표준 및 커스텀 에이전트 대화 모두에서 컴포저 아래에 현지화된 AI 생성 콘텐츠 면책 조항을 표시하여 사용자에게 중요한 정보를 확인할 것을 상기시킵니다.

중단된 첫 번째 턴 실행도 폴백 대화 제목을 유지하므로 스트리밍 응답을 중지해도 새로 고침 후 스레드가 "제목 없음(Untitled)"으로 남지 않습니다.

스트리밍 마크다운 응답은 새로 도착한 단어만 애니메이션 처리합니다. 이미 보이는 텍스트는 다음 청크가 동일한 블록을 확장할 때 페이드 아웃되었다가 다시 재생되지 않습니다.

웹 UI에서는 완료된 어시스턴트 턴을 새 메인 대화로 분기(branch)할 수 있습니다. 새 스레드는 해당 턴의 체크포인트에서 시작하고 이전 재생 체크포인트를 유지하므로 분기된 응답을 즉시 재생성할 수 있습니다. 최신 응답은 스트리밍된 부분 텍스트가 체크포인트에 도달하지 않은 경우에도 중단 후에 다시 생성할 수 있습니다. 최신 응답을 재생성해도 원래 응답 후에 수동으로 이름을 바꾼 제목을 포함하여 스레드의 현재 제목이 유지됩니다. 체크포인트 부모 링크가 없는 레거시 또는 가져온 이력은 경계가 지정된 연대순 폴백을 사용합니다. 이전 재생 체크포인트가 없는 경우 레거시 단일 체크포인트 형태로 분기 작업이 여전히 성공하며, 상속된 응답에 대해서는 재생성이 계속 불가능합니다. 기존 단일 체크포인트 분기는 안전하지 않은 체크포인트 복사를 시도하는 대신 그대로 유지됩니다. 워크스페이스 파일은 체크포인트되지 않으므로 최신 턴에서 분기할 때 분기는 현재 워크스페이스의 베스트 에포트 복사본만 받습니다. 오래된 턴에서 분기하면 복원된 메시지 이력만 유지되므로 분기가 대화의 후반부에 생성된 파일을 상속하지 않습니다.

웹 UI는 실행당 완료된 작업 시간을 한 번 보고합니다. 이는 모델 추론, 툴 호출, 대기를 포함한 총 월클록(wall-clock) 시간이며 단계별 또는 모델 전용 사고 시간이 아닙니다. 추론 콘텐츠는 자체적인 별도의 공개(disclosure)를 통해 계속 사용할 수 있습니다.

웹 UI에서는 메시지 툴바에서 가장 최근에 완료된 사용자 턴을 편집하고 다시 실행할 수도 있습니다. DeerFlow는 해당 사용자 메시지 이전의 대화 체크포인트를 복원하고, 편집된 텍스트를 새 사용자 메시지로 제출하며, 재생이 진행 중이거나 성공하면 대체된 턴을 숨깁니다. 이는 대화 상태 재생일 뿐이며 파일, 메모리 업데이트, 외부 툴 부수 효과는 취소되지 않습니다.

웹 UI 채팅 링크는 경로 세그먼트에 배치하기 전에 커스텀 스레드 식별자를 백분율 인코딩하므로 `#` 및 `?`와 같은 예약된 URL 문자가 열리는 대화를 변경하지 않습니다.

```
# 샌드박스 컨테이너 내부 경로
/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      ← 사용자 정의 스킬

/mnt/skills/integrations
└── lark-cli/lark-doc/SKILL.md      ← 관리형, 읽기 전용
```

#### Claude Code Integration

`claude-to-deerflow` 스킬을 사용하면 [Claude Code](https://docs.anthropic.com/en/docs/claude-code)에서 실행 중인 DeerFlow 인스턴스와 직접 상호작용할 수 있습니다. 터미널을 떠나지 않고도 연구 작업을 보내고, 상태를 확인하고, 스레드를 관리할 수 있습니다.

**스킬 설치**:

```bash
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(서브에이전트)
- DeerFlow 상태 확인, 모델/스킬/에이전트 나열
- 스레드 및 대화 이력 관리
- 분석을 위한 파일 업로드

**환경 변수** (선택 사항, 커스텀 엔드포인트용):

```bash
DEERFLOW_URL=http://localhost:2026            # 통합 프록시 기본 URL
DEERFLOW_GATEWAY_URL=http://localhost:2026    # 게이트웨이 API
DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph  # LangGraph API
```

전체 API 참조는 [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md)를 참조하십시오.

### Session Goals

`/goal <completion condition>`을 사용하여 하나의 활성 완료 조건을 현재 스레드에 첨부할 수 있습니다. 목표는 스킬 활성화가 아니라 스레드 범위의 상태이므로, DeerFlow가 충족되었다고 판단하거나 사용자가 지울 때까지 턴 전반에 걸쳐 활성 상태로 유지됩니다.

지원되는 명령어:

```text
/goal finish the implementation and make all tests pass
/goal              # 활성 목표 표시
/goal clear        # 목표 지우기
```

각 게이트웨이 기반 실행 후, DeerFlow는 사고(thinking) 기능이 없는 평가자 모델을 사용하여 활성 목표에 대해 보이는 대화를 평가합니다. 평가자는 유형화된 차단기(`missing_evidence`, `needs_user_input`, `run_failed`, `external_wait` 또는 `goal_not_met_yet`)와 가시적인 증거를 반환해야 합니다. DeerFlow는 가장 최근 어시스턴트 턴이 내구성 있게 체크포인트되고, 차단기가 `goal_not_met_yet`이며, 평가 중에 스레드가 변경되지 않고, 진전 없음 브레이커(no-progress breaker)가 작동하지 않은 경우에만 숨겨진 연속(continuation)을 주입합니다. 안전 제한은 기본적으로 8개의 숨겨진 연속으로 설정되며, 반복되는 동일한 진전 없음 평가는 2회 시도 후 중단됩니다. `/goal clear` 및 사용자가 작성한 모든 새 입력은 대기 중인 연속보다 우선합니다. 목표가 충족되면 DeerFlow는 이를 자동으로 지우고 업데이트된 스레드 상태를 발행합니다.

웹 UI는 컴포저 위에 활성 목표를 표시합니다. 동일한 명령어를 TUI 및 지원되는 IM 채널에서 사용할 수 있습니다. 웹 UI 및 지원되는 IM 채널에서 `/goal <completion condition>`을 설정하면 해당 조건을 작업으로 하는 실행도 시작됩니다. 상태 및 지우기 명령어는 목표 페이지만 관리합니다. 해당 스레드에 진행 중인 실행(다른 게이트웨이 워커가 소유한 실행 포함)이 있는 경우 목표 설정 또는 지우기가 거부되므로 목표 체크포인트가 활성 실행의 체크포인트 계보에서 멀어지게 분기될 수 없습니다.

### Manual Context Compaction

웹 UI 컴포저에서 `/compact`를 사용하여 현재 스레드의 오래된 컨텍스트를 요약할 수 있습니다. DeerFlow는 전체 채팅을 계속 표시하지만 향후 모델 호출은 압축된 요약과 최근 메시지를 사용합니다. 압축할 충분한 이력이 없는 경우 이 명령어는 무시되며, 스레드에 진행 중인 실행(다른 게이트웨이 워커가 소유한 실행 포함)이 있는 동안에는 차단됩니다. 다중 워커 예약이 임대를 잃으면 DeerFlow는 대체 실행이 진행되기 전에 체크포인트 작성기를 취소하고 정리 후 재시도 가능한 충돌을 반환합니다. 스레드 제목 편집은 동일한 상태 쓰기 경계를 통해 직렬화되며, 실행 중일 때 이름 바꾸기 대화 상자를 닫지 않고 충돌을 표시합니다.

또한 선택한 모델에 양수의 `context_window`가 설정되어 있는 경우 채팅 헤더에 컨텍스트 윈도우 게이지가 표시됩니다. 이는 가장 최근에 구체화된 체크포인트의 메시지 토큰을 추정하고, 누적 토큰 사용량 설정과 무관하게 데이터가 다시 페치되는 동안 이전의 동일 스레드 백분율을 계속 볼 수 있도록 유지합니다.

### Sub-Agents

서브 에이전트는 최적화일 뿐 복잡한 요청에 대한 기본 응답이 아닙니다.

리드 에이전트는 실제 병렬 지연 시간, 전문가 역량 또는 컨텍스트 격리로부터 명확한 순 이점이 있을 때 각각 자체 범위의 컨텍스트, 툴, 종료 조건을 가진 서브 에이전트를 즉석에서 생성할 수 있습니다. 상호 의존적인 범위와 겹치는 부수 효과는 병렬 디스패치에서 제외되며, 전문가 또는 컨텍스트 격리 이점이 명확하게 승리할 때 경계가 지정된 순차적 체인이 하나의 서브 에이전트에서 계속 실행될 수 있습니다. 리드는 가장 유용한 수의 서브 에이전트를 사용하고, 단순히 작업이 크거나 다단계라는 이유만으로 팬아웃(fan out)하는 대신 나중에 배치를 다시 평가합니다. 서브 에이전트는 구조화된 결과를 보고하고, 리드 에이전트는 이를 검증하여 일관된 출력으로 종합합니다. 설정된 스킬은 리드 에이전트와 동일한 사용자 범위 카탈로그에서 해결되므로 사용자가 소유한 커스텀 스킬은 다른 사용자의 버전을 노출하지 않고도 계속 사용할 수 있습니다. 내부 AI 및 툴 메시지는 부모 채팅 스트림에 들어가는 대신 위임된 그래프에 국한되어 유지됩니다. 다시 로드된 스레드 기록은 동일한 경계를 강제합니다. 콜백에 의해 캡처된 서브 에이전트 AI 응답은 실행 이벤트 진단에서 계속 사용할 수 있지만 부모 대화 기록에서는 제외되며, 부모 `task` 결과는 하위 작업 카드에 계속 첨부됩니다. 장기 실행 서브 에이전트는 요약이 활성화되면 오래된 기록을 압축하고 계속하기 전에 요약을 보호되고 숨겨진 지속형 컨텍스트로 다시 주입하므로 최근 어시스턴트/툴 활동이 작업에 기반을 둔 상태로 유지됩니다. 제공자/모델 요청 실패는 성공적인 결과가 아니라 실패한 서브 에이전트 작업으로 보고되므로 리드 에이전트와 웹 UI가 이에 올바르게 반응할 수 있습니다. 축소된 서브 에이전트 카드에는 유효한 모델과 (제공자가 사용량 메타데이터를 반환하는 경우) 각 완료된 서브 에이전트 LLM 호출 후에 업데이트되고 다시 로드된 후에도 유지되는 누적 토큰 총계가 표시됩니다. 토큰 사용량 추적이 활성화되면 완료된 서브 에이전트 사용량도 디스패치 단계에 다시 귀속됩니다.

예를 들어, 월클록 절감이 중복된 검색 및 종합 비용보다 클 때 독립적인 읽기 전용 연구가 동시에 실행될 수 있는 반면, 공유 파일과 순차적 테스트 피드백이 있는 리포지토리 리팩토링은 리드 에이전트에 남습니다. `max_concurrent_subagents`가 `1`인 경우 병렬 및 다중 배치 라우팅 가이던스가 비활성화되며, 위임은 중요한 전문가 또는 컨텍스트 격리 이점이 있는 경우에만 유지됩니다.

### Sandbox & File System

`E2BSandboxProvider`는 기본 오버플로우 정책으로 `wait`를 사용합니다. `acquire_timeout` 동안 대기한 다음 에이전트 턴을 실패 처리합니다. DeerFlow는 턴을 자동으로 재시도하지 않습니다. 클라이언트는 구조화된 오류를 사용하여 재시도를 예약할 수 있습니다.

제한된 추가 VM을 허용하려면 `burst_limit`과 함께 `burst`를 사용하십시오. `wait` 및 `reject` 정책은 `replicas`만 사용합니다. `reject` 정책은 오류를 반환하기 전에 웜(warm) VM 하나를 제거할 수 있습니다.

메모리 내 소유권의 경우 `replicas`는 하나의 게이트웨이 프로세스를 제한합니다. Redis 소유권의 경우 E2B는 동일한 `sandbox.ownership.key_prefix`를 사용하는 워커 간에 하나의 용량 Hash를 공유합니다. 이 경우 `replicas`(플러스 구성된 버스트)는 배포 전체의 하드 리미트가 됩니다. 배포당 고유한 프리픽스 하나와 동일한 유효 한도를 사용하십시오. 한도를 변경하려면 게이트웨이를 중지하고 용량 Hash를 삭제한 후 재시작하십시오. 일치하지 않는 워커는 닫힌 상태로 실패합니다.

Hash는 원격 VM과 진행 중인 생성을 카운트하고, E2B 메타데이터에서 중단된 생성을 복구하며, 유예 기간으로 스태일 인벤토리 누락을 보호하고, Redis 또는 초기 인벤토리를 사용할 수 없는 동안 새로운 생성을 차단합니다. 영속성, 비축출 메모리, HA와 함께 Redis를 실행하십시오.

E2B 획득은 바운드된 executor를 사용합니다. 대기 중인 획득은 기본 asyncio executor를 사용하지 않습니다.

E2B VM은 E2B가 파괴를 확인할 때까지 슬롯을 유지합니다. 이 규칙은 생성 및 회수 작업에 적용됩니다. 검색은 다른 게이트웨이의 VM을 찾을 수 있습니다. 종료(shutdown)는 VM을 파괴하지 않고 소유되지 않은 검색 클라이언트를 닫습니다. 해제(release)는 VM이 웜 풀에 들어갈 때 전환 카탈로그를 중지합니다. 종료 레이스는 일시적인 강제 종료 실패 후 원격 정리를 재시도합니다. 재설정(reset)은 추적된 활성 및 웜 E2B VM을 파괴합니다. 이전 제공자 인스턴스는 새로운 획득을 수락할 수 없습니다.

DeerFlow는 단순히 무엇을 하겠다고 *말만* 하는 것이 아닙니다. 자체 컴퓨터가 있습니다.

각 작업은 스킬, 워크스페이스, 업로드, 출력을 포함하는 전체 파일 시스템 뷰를 갖춘 자체 실행 환경을 얻습니다. 에이전트는 파일을 읽고, 쓰고, 편집합니다. 이미지를 볼 수 있고 안전하게 설정된 경우 쉘 명령어를 실행할 수 있습니다.

내장 `grep` 툴은 단일 텍스트 파일 또는 디렉토리 아래의 모든 일치하는 텍스트 파일을 검색하므로, 에이전트가 요청을 업로드 디렉토리 전체로 먼저 넓히지 않고도 업로드된 문서를 직접 검색할 수 있습니다.

비전 모델 호출을 위해 로드된 이미지 바이트는 일시적입니다. DeerFlow는 모델이 소비한 후 숨겨진 base64 메시지를 제거하므로 이후 체크포인트가 해당 페이로드를 계속 복제하지 않습니다.

각 실행 후, DeerFlow는 실행이 소유한 `workspace` 및 `outputs` 디렉토리에 대한 워크스페이스 변경 요약을 기록합니다. 웹 UI는 어시스턴트 턴에 컴팩트한 "files changed" 배지를 표시하며, 이를 열면 표시하기에 안전한 경우 텍스트 차트와 함께 생성, 수정, 삭제된 파일이 드러납니다. 업로드는 사용자 입력이지 에이전트가 생성한 변경 사항이 아니므로 제외됩니다. 크고, 바이너리이거나, 민감해 보이는 파일은 메타데이터로만 표시됩니다.

`present_files`를 통해 제공되는 파일은 스레드의 아티팩트 상태의 일부로 유지되며, 웹 UI는 페이지 새로 고침 후 아티팩트 패널과 선택한 문서를 복원합니다. 현재 선택된 공식 아티팩트는 수동으로 다시 로드하지 않고도 편집 내용을 볼 수 있도록 실행이 완료될 때 한 번 새로 고쳐집니다. `/mnt/user-data/outputs` 아래의 기존 UTF-8 텍스트 아티팩트는 스레드가 유휴 상태일 때 유닉스 및 윈도우 패널에서 직접 편집하고 명시적으로 저장할 수도 있습니다. 저장은 에이전트 변경 사항이 덮어쓰여지는 것을 방지하기 위해 콘텐츠 리비전을 사용합니다.

텍스트 아티팩트는 HTTP 바이트 범위(byte-range) 지원과 함께 스트리밍됩니다. 웹 UI는 처음에 최대 1 MiB를 로드하고, 파일이 더 큰 경우 미리보기 크기를 표시하며, 나머지 부분을 페치하거나 전체 코드 에디터를 마운트하기 전에 명시적인 **Load full file** 작업을 기다립니다. 활성 HTML, XHTML 및 SVG 아티팩트는 게이트웨이 경계에서 강제 다운로드 상태로 유지됩니다.

`AioSandboxProvider`를 사용하면 쉘 실행이 격리된 컨테이너 내에서 실행됩니다. `LocalSandboxProvider`를 사용하면 파일 툴이 여전히 호스트의 스레드별 디렉토리에 매핑되지만, 보안 격리 경계가 아니므로 호스트 `bash`는 기본적으로 비활성화됩니다. 완전히 신뢰할 수 있는 로컬 워크플로우에 대해서만 호스트 bash를 다시 활성화하십시오. 호스트 bash 명령어에는 월클록 타임아웃이 있으며, 장기 실행 프로세스는 워크스페이스 로그로 출력이 리디렉션된 상태로 백그라운드에서 시작되어야 합니다.

`AioSandboxProvider`는 일반적으로 백엔드에서 스레드 데이터 마운트를 감지합니다. 로컬 컨테이너는 마운트된 게이트웨이 디렉토리를 사용하는 반면, 원격/프로비저너 샌드박스는 명시적인 동기화를 통해 업로드된 파일을 받습니다. 양쪽 모두 동일한 스레드 사용자 데이터 디렉토리를 공유하는 것이 보장되는 배포에서는 `sandbox.thread_data_mounts: true`를 설정하여 업로드별 샌드박스 획득 및 동기화를 건너뛸 수 있습니다. 자동 감지를 위해 해당 필드를 설정하지 않은 상태로 두십시오. 잘못 설정하면 업로드된 파일을 샌드박스 내부에서 사용할 수 없게 될 수 있습니다.

이것이 툴 액세스 권한이 있는 챗봇과 실제 실행 환경이 있는 에이전트의 차이입니다.

```
# 샌드박스 컨테이너 내부 경로
/mnt/user-data/
├── uploads/          ← 사용자의 파일
├── workspace/        ← 에이전트의 작업 디렉토리
└── outputs/          ← 최종 산출물
```

### Agentic Browser Control

페이지를 읽는 것은 페이지를 *사용*하는 것과 다릅니다. 읽기 전용 `web_fetch` 및 `web_capture` 툴 외에도 DeerFlow는 대화당 라이브 브라우저 세션을 유지하는 선택적 에이전트 브라우저 툴 그룹을 제공하므로 에이전트가 실제로 페이지를 조작할 수 있습니다(탐색, 대화형 요소 읽기, 클릭, 입력, 폼 제출, 자바스크립트가 많은 사이트의 다단계 흐름 팔로우).

각 작업은 안정적인 `[ref]` 번호로 주소가 지정된 페이지의 대화형 요소에 대한 최신 스냅샷을 반환하므로, 에이전트는 셀렉터를 추측하는 대신 방금 관찰한 내용을 바탕으로 행동합니다. 아웃바운드 URL은 기본적으로 SSRF 스크리닝됩니다. Playwright로 구동되며 핵심 설치를 가볍게 유지하기 위해 선택적 추가 기능으로 제공됩니다:

```bash
cd backend
uv sync --extra browser
uv run playwright install chromium
```

그런 다음 `config.yaml`의 `group: browser` 툴 항목(`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_get_text`, `browser_back`, `browser_screenshot`, `browser_close`)의 주석을 해제하세요. `make dev` / Docker 시작은 활성화된 `browser_navigate` 툴을 감지하고 의존성 동기화 시 `browser` extra를 보존합니다. 브라우저 제어가 설정되었으나 Playwright가 누락된 경우 게이트웨이는 시작에 실패하며, 백엔드가 실제로 서비스를 제공할 수 없는 경우 `/api/features`는 브라우저 UI를 숨깁니다. 로컬 및 신뢰할 수 있는 디버깅 외의 모든 용도에는 `headless: true` 및 `allow_private_addresses: false`를 유지하십시오. `cdp_url`을 사용하여 기존 Chrome에 연결하는 것은 DeerFlow의 서브리소스/리다이렉트 SSRF 보호를 강제할 수 없으므로 `allow_unguarded_cdp: true`가 해당 위험을 명시적으로 승인하지 않는 한 닫힌 상태로 실패합니다. 신뢰할 수 있는 로컬 브라우저에서만 사용하십시오. 브라우저 세션은 프로세스 로컬입니다. 일반 uvicorn 워커 디스패치는 스레드 친화성(affinity)을 제공하지 않으므로 이 툴 그룹이 활성화되어 있는 동안에는 `GATEWAY_WORKERS=1`을 유지하십시오.

워크스페이스 Browser Live 클라이언트는 바이너리 JPEG WebSocket 프레임을 협상하고 디스플레이 새로 고침당 가장 최신 대기 중인 프레임만 유지하며 교체된 객체 URL을 취소합니다. 게이트웨이 제어 메시지는 JSON으로 유지되며 바이너리 기능을 요청하지 않는 클라이언트는 레거시 JSON/base64 프레임 프로토콜을 유지합니다.

### Context Engineering

**격리된 서브 에이전트 컨텍스트(Isolated Sub-Agent Context):** 각 서브 에이전트는 자체 격리된 컨텍스트에서 실행됩니다. 즉, 서브 에이전트는 메인 에이전트나 다른 서브 에이전트의 컨텍스트를 볼 수 없습니다. 이는 서브 에이전트가 메인 에이전트나 다른 서브 에이전트의 컨텍스트에 방해받지 않고 당면한 작업에 집중할 수 있도록 보장하는 데 중요합니다.

**요약(Summarization):** 세션 내에서 DeerFlow는 완료된 하위 작업을 요약하고, 중간 결과를 파일 시스템으로 오프로드하며, 즉시 관련성이 없는 내용을 압축하는 등 컨텍스트를 적극적으로 관리합니다. 이를 통해 컨텍스트 윈도우를 초과하지 않고 길고 복잡한 다단계 작업 전반에서 예리함을 유지할 수 있습니다.

**엄격한 툴 호출 복구(Strict Tool-Call Recovery):** 제공자나 미들웨어가 툴 호출 루프를 중단할 때, DeerFlow는 이제 강제 중단된 어시스턴트 메시지에서 제공자 수준의 원시 툴 호출 메타데이터를 제거하고 다음 모델 호출 전에 매달려 있는(dangling) 호출에 대한 플레이스홀더 툴 결과를 주입합니다. 이를 통해 엄격하게 `tool_call_id` 시퀀스를 검증하는 OpenAI 호환 추론 모델이 잘못된 형식의 기록 오류로 실패하지 않도록 방지합니다.

**가시적 툴 실행 완료(Visible Tool-Run Completion):** 대화형 턴의 경우, DeerFlow는 빈 툴 후 최종 응답을 한 번 재시도한 다음 조용한 성공 실행을 보고하는 대신 가시적인 오류를 표시합니다.

### Long-Term Memory

대부분의 에이전트는 대화가 끝나는 순간 모든 것을 잊어버립니다. DeerFlow는 기억합니다.

또한 DeerFlow에는 선택적인 `openviking` 메모리 백엔드가 포함되어 있습니다. 독립형 OpenViking 서버에 HTTP로 연결하고, 완료된 턴을 OpenViking Sessions를 통해 제출하며, DeerMem을 기본값으로 유지하면서 프롬프트 주입을 위해 원격 메모리를 리콜합니다. 초기 통합은 `memory.mode: middleware`를 지원합니다. 경계가 지정된 제출된 메시지 워터마크는 길고 압축된 기록을 다루며 실패한 세션 커밋이 재시도시 이미 수락된 메시지를 중복 생성하는 것을 방지합니다. 공유 HTTP client에도 명시적인 연결 제한과 지연된 재시도가 있습니다. 설정 및 Docker 시작에 대해서는 [OpenViking memory backend](docs/OPENVIKING.md)를 참조하십시오.

세션을 넘어 DeerFlow는 사용자의 프로필, 선호도, 축적된 지식에 대한 지속적인 메모리를 구축합니다. 사용할수록 작성 스타일, 기술 스택, 반복되는 워크스페이스 등 사용자를 더 잘 파악하게 됩니다. 메모리는 로컬에 저장되며 사용자의 통제 하에 유지됩니다.

DeerMem은 기본 로컬 백엔드로 유지됩니다. 호스팅된 mem0 플랫폼 API 또는 API 호환 자체 호스팅 서버를 위해 선택 사항인 `mem0` 백엔드도 사용할 수 있습니다. 토큰을 보유하는 `base_url`은 기본적으로 HTTPS를 사용해야 하며, 일반 텍스트 HTTP는 명시적인 로컬 개발 opt-in이 필요합니다. [mem0 백엔드 가이드(mem0 backend guide)](backend/packages/harness/deerflow/agents/memory/backends/mem0/README.md)를 참조하십시오.

메모리 업데이트는 이제 적용 시점에 중복 팩트 항목을 건너뛰므로 반복되는 선호도와 컨텍스트가 세션을 거치며 끝없이 누적되지 않습니다.

기본 DeerMem `middleware` 모드에서는 자동 추출이 결정론적 쓰기 게이트가 이를 수락하기 전에 제안된 모든 팩트를 범위, 내구성, 권한별로 분류합니다. 지속적이고 설명적인 사용자 수준의 팩트만 저장되며 현재 스레드나 프로젝트 제약 조건 및 일회성 작업 권한은 대화 상태에 유지됩니다. 사용자 전역 요약에는 사용자 범위와 설명적 권한이 모두 필요하며, 모순 제거는 범위가 지정되고, 대체 의존적 제거는 대체가 실제로 검증 및 스토리지를 통과할 때만 적용됩니다. 이러한 분류 레이블은 추출 전용 메타데이터이며 추가 LLM 호출을 추가하지 않고 팩트 파일에 기록되지 않습니다. `memory.mode: tool`의 명시적인 CRUD 툴은 별도의 모델 지향 경로로 유지됩니다. `memory.backend_config.prompts_dir`를 통해 번들된 DeerMem 프롬프트를 재정의하는 배포는 새로운 분류 필드를 커스텀 템플릿(`memory_update` 팩트/요약/제거 형식 및 `consolidation` 통합 팩트 스키마)에 추가해야 합니다. 쓰기 게이트가 닫힌 상태로 실패하므로 마이그레이션되지 않은 템플릿은 추출 기반 팩트, 요약 및 제거 쓰기를 모두 중단시키고 `rejected_by_scope_gate` 메트릭과 높은 거부율 경고를 통해서만 나타납니다.

파일 기반 메모리는 이제 전역 사용자 컨텍스트를 에이전트 팩트와 분리합니다. 각 사용자에게는 프로젝트와 무관한 `user` 및 `history` 요약만 포함된 `memory.json`이 하나씩 있습니다. 모든 팩트는 `agents/{agent_name}/facts/` 아래의 표준 마크다운 파일입니다. `agent_name`을 생략하는 기존 리드 에이전트 미들웨어, API, 설정, 가져오기/내보내기 및 임베디드 클라이언트 호출은 DeerMem 내부에서 예약된 `__default__` 버킷으로 해결됩니다. 해당 버킷은 유효한 커스텀 에이전트 이름 문법 외부이므로 `lead-agent`라는 이름의 실제 커스텀 에이전트는 별도의 팩트 저장소를 가지며 커스텀 에이전트를 삭제해도 `config.yaml` 없이 메모리 전용 디렉토리를 삭제할 수 없습니다. 공개 에이전트 식별자는 대소문자를 구분하지 않으며 소문자로 정규화됩니다. 런타임/API 독자는 선택된/기본 에이전트에 대한 호환성 `facts` 배열을 계속 받으므로 프론트엔드가 `memory.json`에서 에이전트 팩트를 읽지 않습니다. 구조화된 마크다운 `source` 메타데이터는 MemoryManager 경계에서 과거의 문자열 필드로 프로젝션됩니다. 범위가 지정되지 않은 Clear All은 먼저 읽지 않은 레거시 에이전트별 JSON에서 곧 지워질 요약을 채택하지 않고 팩트를 마이그레이션한 다음, 에이전트 설정 파일을 보존하면서 모든 에이전트 버킷에서 공유 요약과 팩트를 제거하므로 나중에 읽을 때 건너뛴 레거시 팩트가 부활할 수 없습니다. 명시적으로 에이전트 범위가 지정된 지우기는 해당 에이전트의 팩트만 제거합니다. 첫 번째 일반 읽기 시 사용자 JSON에 임베디드된 오래된 팩트는 `__default__`로 자동 마이그레이션되며, 이전의 암시적 `lead-agent` 버킷에 작성된 팩트도 해당 디렉토리가 실제 커스텀 에이전트가 아닌 경우 이동됩니다. 마이그레이션 및 일반 쓰기는 지속형 스토리지 락이 해제된 후에만 설정된 검색 어댑터에 알립니다. DeerMem은 기본적으로 범위 인식 SQLite FTS5/BM25 어댑터를 사용하고, `.retrieval/` 아래에 재구축 가능한 파생 인덱스 데이터만 저장하며, 게이트웨이 시작 시 백그라운드에서 또는 범위 지정 검색 시 지연 로딩으로 이를 재구축합니다. 손상된 파생 인덱스는 자동으로 다시 생성됩니다. 이를 비활성화하고 로컬 부분 문자열 폴백을 사용하려면 `memory.backend_config.retrieval_adapter`를 빈 문자열로 설정하십시오. 중국어 토큰화는 선택 사항이며, jieba 기반 하위 구문 검색을 위해 백엔드 `memory-zh` extra(`uv sync --extra memory-zh`)를 설치하십시오. 저널링된 쓰기, 공유 사용자 락, 낙관적 사용자 메모리 리비전은 조용한 업데이트 유실을 방지합니다.

메모리 주입은 설정된 작업 모드를 따릅니다. `middleware` 모드에서 DeerMem은 사용자 전역 요약과 선택된 에이전트의 팩트를 주입합니다. `tool` 모드에서 자동 `<memory>` 블록에는 전역 `user` 및 `history` 요약만 포함되며, 에이전트 팩트는 `memory_search`를 통해 명시적으로 검색되어 중복된 자동 및 툴 반환 팩트 컨텍스트를 방지합니다. `memory.injection_enabled: false`를 설정해도 두 모드 모두에서 전체 블록이 비활성화됩니다.

단일 팩트 저장소 작업은 진정으로 증분(incremental) 방식입니다. 업서트/삭제는 대상 팩트 파일만 읽고, 저널링하고, 쓰고, 다시 인덱싱하며, 캐시 종속적인 가짜 전체 문서 대신 명시적인 불완전 델타를 반환합니다. 요약 변경 세트는 지속된 섹션 위에 제공된 `user`/`history` 하위 키를 병합하므로 부분 업데이트가 생략된 형제를 지울 수 없습니다. 전체 가져오기는 대체 값을 적용하기 전에 두 섹션을 모두 완전한 호환성 스키마로 정규화합니다. 매니저/API 호환성 메서드는 공개 응답 계약이 요구할 때만 신선한 전체 문서를 구체화합니다. 팩트 수준의 포인트 작업은 별도의 예상 사용자 메모리와 팩트 리비전을 사용하며 대상 팩트 전제 조건이 모두 유지될 때 명시적으로 리베이스할 수 있습니다. 범위 지정 지우기, 캡이 지정된 생성, 통합, 트리밍과 같은 스냅샷 파생 작업은 오래된 삭제/트리밍 세트를 절대 리플레이하지 않습니다. 매니지먼트 충돌은 전체 문서를 다시 로드하고 제한된 재시도와 함께 작업을 다시 계산합니다. 팩트 경로는 생성된 `fact_*` ID가 샤드에 분산되도록 `SHA-256(fact_id)`의 처음 두 16진수 문자를 사용합니다. 캐시 토큰은 공유 JSON의 나노초 mtime, 크기 및 지속형 리비전을 결합하므로 거친 mtime의 동일한 크기 쓰기가 팩트 파일을 스캔하지 않고 오래된 데이터를 반환하는 것을 방지합니다. 직접 대역 외(out-of-band) 마크다운 편집은 명시적인 다시 로드가 필요합니다. 스토리지 관련 충돌 및 손상은 MemoryManager 경계에서 변환됩니다. 게이트웨이는 충돌을 HTTP 409로 반환하고 민감하지 않은 안정적인 손상 오류를 HTTP 500으로 반환합니다. 전체 문서 `save()`는 호환성 API로 유지되며 쓰기 전에 diff를 계산합니다. 잘못되거나 누락된 `facts`는 에이전트의 마크다운 파일을 조용히 지울 수 없습니다. 레거시 마이그레이션은 에이전트 `memory.json`을 삭제하기 전에 비어 있지 않은 `user`/`history`를 보존하며, 충돌하는 요약은 승자를 선택하는 대신 레거시 파일을 유지하고 크게 실패합니다.

`memory.json`의 레거시 팩트는 사용자의 첫 번째 일반 메모리 읽기 시 예약된 `__default__` 마크다운 버킷으로 자동 마이그레이션됩니다. 트래픽을 서브하기 전에 마이그레이션을 감사하거나 완료하려는 운영자는 `backend/`에서 선택적 거치형(idempotent) CLI를 실행할 수 있습니다:

```bash
PYTHONPATH=. python scripts/migrate_memory_markdown.py --all-users --dry-run
PYTHONPATH=. python scripts/migrate_memory_markdown.py --all-users
# 커스텀 DeerMem 루트 또는 원래 디렉토리에 안전하지 않은 식별자는 명시적일 수 있음:
PYTHONPATH=. python scripts/migrate_memory_markdown.py --storage-path /path/to/deerflow-home --user-id 'test@example.com'
```

v1에서 v2로의 스토리지 마이그레이션은 실행 중인 애플리케이션에 대해 단방향입니다. PR 이전 코드는 마크다운 팩트를 읽지 않습니다. 지속형 배포를 업그레이드하기 전에 DeerFlow를 중지하고 구성된 메모리 스토리지 루트의 파일 시스템 스냅샷이나 전체 백업을 수행하십시오. 또한 마이그레이션은 v2 데이터를 쓰기 전에 `{manifest_filename}.v1.bak`으로 원래 경로 옆에 각 파괴적인 JSON 소스를 내구성 있게 보관합니다. 기존 불일치 백업 또는 백업 쓰기 실패는 v1 소스를 수정하지 않고 마이그레이션을 중단합니다. 이 로컬 백업은 마이그레이션 이전 데이터를 보존하지만 전체 스냅샷을 대체할 수 없으며 업그레이드 후에 생성된 팩트는 포함하지 않습니다.

`--user-id`는 반복될 수 있습니다. `--all-users`는 선택한 스토리지 루트 아래에 있는 기존의 디렉토리 안전 버킷을 검색합니다. `@`와 같은 문자가 포함된 원시 ID를 전달한 독립형 통합은 `--user-id`와 함께 원래 값을 사용해야 합니다. 실패한 사용자의 마이그레이션은 나머지 감사를 숨기지 않고 보고되며, 사용자 중 하나라도 실패하면 명령어가 0이 아닌 값으로 종료됩니다. 자동 첫 읽기 경로는 계속 활성화되므로 이 CLI를 실행할 필요는 없습니다.

## Recommended Models

DeerFlow는 모델에 구애받지 않으며(model-agnostic), OpenAI 호환 API를 구현하는 모든 LLM에서 작동합니다. 즉, 다음과 같은 기능을 지원하는 모델에서 가장 잘 작동합니다:

- 심층 연구 및 다단계 작업을 위한 **긴 컨텍스트 윈도우** (100k+ 토큰)
- 적응형 계획 및 복잡한 분해를 위한 **추론 기능**
- 이미지 이해 및 비디오 이해를 위한 **멀티모달 입력**
- 안정적인 함수 호출 및 구조화된 출력을 위한 **강력한 툴 사용 능력**

## Embedded Python Client

DeerFlow는 전체 HTTP 서비스를 실행하지 않고도 임베디드 Python 라이브러리로 사용할 수 있습니다. `DeerFlowClient`는 모든 에이전트 및 게이트웨이 기능에 대한 프로세스 내 직접 액세스를 제공하며, HTTP 게이트웨이 API와 동일한 응답 스키마를 반환합니다. 또한 HTTP 게이트웨이는 LangGraph 스레드 자체가 삭제된 후 DeerFlow 관리형 로컬 스레드 데이터를 제거하기 위해 `DELETE /api/threads/{thread_id}`를 노출합니다.

스레드 ID는 호출자에 의해 제공될 수 있으며 UUID일 필요는 없습니다. 명시적 ID는 1~64개의 ASCII 문자, 숫자, 하이픈 또는 언더스코어(`^[A-Za-z0-9_-]{1,64}$`)를 포함해야 합니다. DeerFlow는 `thread_id`가 생략되거나 `None`인 경우에만 UUID를 생성하며 명시적으로 제공된 빈 문자열은 유효하지 않습니다.
이전의 느슨한 규칙에 따라 생성된 기존 경로 주소 지정 가능한 스레드는 계속 읽고 삭제할 수 있지만 새로운 실행을 시작하거나 새로운 파일 시스템 또는 샌드박스 상태를 생성할 수 없습니다. ID가 표준 계약에 따라 안전하지 않은 경우 레거시 삭제는 local path cleanup을 건너뜁니다. 대화가 LangGraph 체크포인트에만 존재하는 표준 레거시 스레드의 경우, DeerFlow는 첫 번째 새 실행 전에 체크포인트에서 빈 실행 이벤트 피드를 시드하여 `/messages/page`가 이전 턴과 새 턴을 모두 유지하도록 합니다.

```python
from deerflow.client import DeerFlowClient

client = DeerFlowClient()

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

# 스트리밍 (LangGraph SSE 프로토콜: 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"])
    elif event.type == "messages-tuple" and event.data.get("type") == "tool" and "artifact" in event.data:
        # 구조화된 툴 아티팩트 (예: ask_clarification 카드)는
        # ToolMessage가 제공할 때 보존됩니다.
        print(event.data["artifact"])

# 설정 및 관리 — 게이트웨이 정렬된 딕셔너리 반환
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": {...}} 또는 {"goal": None}
client.clear_goal("thread-1")
```

HTTP 게이트웨이는 `values`, `messages-tuple`, `updates`, `debug`, `tasks`, `checkpoints`, `custom` 스트림 모드를 허용합니다. `messages` 및 `events`와 같은 지원되지 않는 모드, 웹훅, 지연된 실행, `multitask_strategy="enqueue"`와 같은 지원되지 않는 기본값이 아닌 실행 옵션, 체크포인트 지속성 재정의와 같은 선언되지 않은 SDK 옵션은 조용히 무시되거나 다운그레이드되는 대신 실행 전에 `422`를 반환합니다.

딕셔너리를 반환하는 모든 메서드는 CI(`TestGatewayConformance`)에서 게이트웨이 Pydantic 응답 모델에 대해 검증되므로 임베디드 클라이언트가 HTTP API 스키마와 동기화된 상태로 유지됩니다. 전체 API 문서는 `backend/packages/harness/deerflow/client.py`를 참조하세요.

## Scheduled Tasks

DeerFlow에는 이제 워크스페이스에 일급(first-class) 예약 작업 MVP가 포함됩니다.

현재 MVP 기능:

- `/workspace/scheduled-tasks`에서 작업 관리
- 각 예약된 작업이 스레드를 재사용할지 실행당 새 스레드를 생성할지 선택
- `once` 및 `cron` 일정 지원
- 백그라운드 예약 실행을 상호작용 없는 DeerFlow 실행으로 실행 (`ask_clarification`은 거기서 노출되지 않음)
- 동일한 재사용된 스레드의 활성 실행과 충돌하는 예정된 cron 실행에 대해 `skip` 중복(overlap) 행동 사용
- 작업 일시 중지, 재개, 트리거, 이력 검사 및 삭제
- 일반 DeerFlow 실행 생명주기를 통해 예약된 작업 실행

현재 MVP 제한 사항:

- 대화에서 생성된 `schedule_task` 툴은 아직 없음
- 텍스트 전용 알림 작업 없음
- 채널 또는 GitHub 디스패치 타겟 없음
- 이번 첫 릴리스에서는 `interval` 일정 유형 없음

`config.yaml -> scheduler.enabled`로 백그라운드 폴링을 활성화하십시오. 수동 트리거는 동일한 예약 작업 리소스와 실행 경로를 사용합니다.

## Terminal Workbench (TUI)

`deerflow`는 쉘에서 생활하는 사람들을 위한 터미널 네이티브 워크벤치입니다. 게이트웨이, 프론트엔드, nginx, Docker 없이 `DeerFlowClient`를 통해 **임베디드**로 실행되며, 다른 DeerFlow와 동일한 `config.yaml`, 체커포인터, 스킬, 메모리, MCP, 샌드박스 설정을 준수합니다.

![DeerFlow TUI](https://raw.githubusercontent.com/bytedance/deer-flow/main/docs/tui/tui-preview.svg)

```bash
uv pip install 'deerflow-harness[tui]'        # 선택 사항 'textual' 의존성

deerflow                                      # 터미널 UI 실행 (TTY 필수)
deerflow --tui-transparent                    # 터미널의 기본 배경 사용
deerflow --continue                           # 가장 최근 스레드 재개
deerflow --resume THREAD                      # ID로 스레드 재개
deerflow --print "summarize this repo"        # stdout으로 헤드리스 단발성 답변 출력
deerflow --json  "hello"                       # 헤드리스 줄 바꿈 구분 스트림 이벤트
deerflow --recursion-limit 250 --print "task" # 헤드리스 에이전트 루프 제한 재정의
```

스트리밍 대화 기록(마크다운 렌더링된 답변), 컴팩트한 툴 활동 카드, `/` 슬래시 명령어 팔레트, 디스플레이 전용 `/clear`, `/goal` 목표 관리, `/model` 및 `/threads` 피커, 입력 이력, `Esc` / `Ctrl+C` 인터럽트가 있는 키보드 중심 채팅 인터페이스입니다. `/clear`는 스레드나 지속된 대화를 삭제하지 않고 현재 터미널 디스플레이에서 행을 제거하며, `/new`와 `/clear`는 진행 중인 디스플레이 상태를 재설정하는 대신 활성 실행 중에 기다릴 것을 요청합니다. TUI에서 연 세션도 웹 UI 사이드바에 나타납니다. 로컬 기본 사용자 아래에 공유 스레드 저장소를 쓰므로 터미널과 웹이 **게이트웨이를 실행하지 않고도** 동기화 상태를 유지합니다.

전체 가이드는 [backend/docs/TUI.md](backend/docs/TUI.md)를 참조하세요.

## Documentation

- [Contributing Guide](CONTRIBUTING.md) - 개발 환경 설정 및 워크플로우
- [Configuration Guide](backend/docs/CONFIGURATION.md) - 설정 및 구성 지침
- [Architecture Overview](backend/CLAUDE.md) - 기술 아키텍처 세부 정보
- [Backend Architecture](backend/README.md) - 백엔드 아키텍처 및 API 참조

## ⚠️ Security Notice

### Improper Deployment May Introduce Security Risks

DeerFlow는 **시스템 명령어 실행, 리소스 작업, 비즈니스 로직 호출**을 포함하는 핵심 고특권 기능을 보유하고 있으며, 기본적으로 **로컬 신뢰 환경(127.0.0.1 루프백 인터페이스를 통해서만 접근 가능)에 배포**되도록 설계되었습니다. 엄격한 보안 조치 없이 LAN 네트워크, 퍼블릭 클라우드 서버 또는 기타 다중 엔드포인트 접근 가능 환경과 같은 신뢰할 수 없는 환경에 에이전트를 배포하는 경우 다음과 같은 보안 위험이 발생할 수 있습니다:

- **무단 불법 호출**: 권한이 없는 제3자나 악의적인 인터넷 스캐너가 에이전트 기능을 발견하여, 시스템 명령어 및 파일 읽기/쓰기와 같은 고위험 작업을 실행하는 대량의 무단 요청을 트리거하여 심각한 보안 결과를 초래할 수 있습니다.
- **컴플라이언스 및 법적 위험**: 사이버 공격, 데이터 도용 또는 기타 불법 활동을 수행하기 위해 에이전트가 불법적으로 호출되는 경우 법적 책임과 컴플라이언스 위험이 발생할 수 있습니다.

### Gateway Admin Is Equivalent to Code Execution

관리자는 게이트웨이 컨테이너 내부에서 명령어를 실행하는 stdio MCP 서버를 등록할 수 있습니다. API는 이를 허용 목록(기본적으로 `npx`, `uvx`, `DEER_FLOW_MCP_STDIO_COMMAND_ALLOWLIST`를 통해 확장됨)으로 제한하고 임의의 코드를 평가할 인자와 환경 변수를 거부합니다. 이는 심층 방어(defense in depth)이지 경계가 아닙니다. 이러한 런처는 원격 패키지를 가져와 실행하기 위해 존재하므로, **게이트웨이 관리자를 호스트의 코드 실행과 동등한 것으로 취급**하고 그에 따라 권한을 부여하십시오.

### Deployment Defaults

Docker 스택은 위에서 설명한 로컬 신뢰 환경 모델에 맞춰 `127.0.0.1`에서만 진입 포트를 발행합니다. 다른 기기에서 액세스하려면 `.env`에서 `BIND_HOST`를 설정하고(`BIND_HOST=0.0.0.0` 등), 아래의 보안 조치를 마련한 후에만 액세스하도록 하세요.

**호스트가 도달 가능해지기 전에 첫 실행 설정을 완료하세요.** 새로운 인스턴스에는 아직 계정이 없으므로, 루프백 전용이 아닌 배포를 시작한 직후 `/setup`을 통해 관리자 계정을 생성하십시오.

### Security Recommendations

**참고: DeerFlow는 로컬 신뢰 네트워크 환경에 배포하는 것을 강력히 권장합니다.** 교차 기기 또는 교차 네트워크 배포가 필요한 경우 다음과 같은 엄격한 보안 조치를 구현해야 합니다:

- **IP 허용 목록**: `iptables`를 사용하거나 접근 제어 목록(ACL)이 있는 하드웨어 방화벽/스위치를 배포하여 **IP 허용 목록 규칙을 설정**하고 다른 모든 IP 주소의 접근을 거부합니다.
- **인증 게이트웨이**: 리버스 프록시(예: nginx)를 설정하고 **강력한 사전 인증을 활성화**하여 인증되지 않은 모든 접근을 차단합니다.
- **네트워크 격리**: 가능한 경우 에이전트와 신뢰할 수 있는 기기를 다른 네트워크 장치와 격리된 **동일한 전용 VLAN**에 배치합니다.
- **최신 상태 유지**: DeerFlow의 보안 기능 업데이트를 계속 팔로우하십시오.

## Contributing

기여를 환영합니다! 개발 환경 설정, 워크플로우 및 지침은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참조하세요.

백엔드 `make test`는 기본적으로 오프라인이며 라이브 외부 API 커버리지를 제외합니다. 유지보수자는 유효한 루트 `config.yaml` 및 API 자격 증명을 제공한 후 `cd backend && make test-live`를 사용하여 실제 `DeerFlowClient` 통합 스위트를 명시적으로 실행할 수 있습니다. 이 경우 API 비용이 발생하고 로컬 샌드박스, 아티팩트 또는 파일이 생성될 수 있습니다. 직접 pytest 실행에는 추가로 `DEER_FLOW_RUN_LIVE_TESTS=1`이 필요합니다.

회귀 커버리지에는 `backend/tests/`의 Docker 샌드박스 모드 감지 및 프로비저너 kubeconfig 경로 처리 테스트가 포함됩니다.
백엔드 블로킹 IO 진단은 프로젝트 루트에서 `make detect-blocking-io`로 실행할 수 있습니다. 이는 백엔드 이벤트 루프에서 실행될 수 있는 블로킹 IO에 대해 백엔드 비즈니스 코드를 정적으로 스캔하고, 간결한 요약을 출력하며, `.deer-flow/blocking-io-findings.json`에 완전한 JSON 발견 결과를 기록합니다.
JSON에는 `priority`, `location`, `blocking_call`, `event_loop_exposure`, `reason`, `code`가 포함된 컴팩트한 검토 레코드가 포함됩니다.
게이트웨이 아티팩트 서빙은 이제 활성 웹 콘텐츠 형식(`text/html`, `application/xhtml+xml`, `image/svg+xml`)이 인라인 렌더링 대신 첨부파일로 다운로드되도록 강제하여 생성된 아티팩트에 대한 XSS 위험을 줄입니다.

프론트엔드 라우트 자산 예산은 `cd frontend && pnpm perf:check`로 확인할 수 있습니다. 이 도구는 일반 프로덕션 빌드에서 `/login`을 측정한 다음 픽스처 기반 워크스페이스 라우트에 대한 프로덕션 정적 데모 빌드를 수행합니다.
대표 라우트가 참조하는 고유한 JavaScript 및 CSS를 측정하고 상세한 결과를 `.next/performance-results.json`에 기록합니다.

## License

이 프로젝트는 오픈 소스이며 [MIT License](./LICENSE) 라이선스 하에 사용할 수 있습니다.

## Acknowledgments

DeerFlow는 오픈 소스 커뮤니티의 놀라운 작업을 바탕으로 구축되었습니다. DeerFlow를 가능하게 만들어 주신 모든 프로젝트와 기여자들의 노력에 깊이 감사드립니다. 진정으로 우리는 거인의 어깨 위에 서 있습니다.

귀중한 기여를 해주신 다음 프로젝트에 진심으로 감사를 표합니다:

- **[LangChain](https://github.com/langchain-ai/langchain)**: 탁월한 프레임워크가 LLM 상호작용과 체인을 구동하여 원활한 통합과 기능을 가능하게 합니다.
- **[LangGraph](https://github.com/langchain-ai/langgraph)**: 멀티 에이전트 오케스트레이션에 대한 혁신적인 접근 방식은 DeerFlow의 정교한 워크플로우를 구현하는 데 중추적인 역할을 했습니다.

이러한 프로젝트들은 오픈 소스 협업의 변혁적인 힘을 보여주며, 우리는 그 기반 위에 구축하게 된 것을 자랑스럽게 생각합니다.

### Key Contributors

DeerFlow의 비전, 열정, 헌신으로 이 프로젝트를 탄생시킨 핵심 작성자들에게 진심으로 감사드립니다:

- **[Daniel Walnut](https://github.com/hetaoBackend/)**
- **[Henry Li](https://github.com/magiccube/)**

흔들리지 않는 헌신과 전문성이 DeerFlow 성공의 원동력이 되었습니다. 이 여정의 항해를 맡아주셔서 영광입니다.

## Star History

[![Star History Chart](https://api.star-history.com/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.com/#bytedance/deer-flow&Date)

deer-flow

deer-flow 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

deer-flow

deer-flow 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README