deer-flow-manager

DeerFlow 2.0（字节跳动开源 Deep Research 框架）管理技能。 用于安装、配置、更新、卸载 DeerFlow 2.0，以及排查启动问题。 触发词：DeerFlow部署、DeerFlow安装、DeerFlow配置、DeerFlow更新、DeerFlow卸载、DeerFlow启动、deer-flow

Security Scan

The skill’s instructions generally match an installer/manager for DeerFlow, but it directs running remote install scripts and asks for model API keys without declaring them—those are legitimate for an installer but riskier than a purely local guide and deserve extra review before running.

Purpose & Capability

Name and description (manage DeerFlow lifecycle) align with the instructions: OS detection, dependency checks, cloning the DeerFlow repo, configuring models, install/update/uninstall flows and troubleshooting. The requested operations (install packages, clone repo, edit config.yaml, run make) are expected for a deployment helper.

Instruction Scope

Instructions ask the user to provide model API credentials and show config templates using environment variables (e.g., $OPENAI_API_KEY, $ANTHROPIC_API_KEY). The skill does not instruct the agent to read unrelated files or exfiltrate secrets, but it does direct editing and storing of API keys in config/.env which is normal for this purpose. The SKILL.md gives broad discretion to run system package installs and curl|sh bootstrap scripts—this is within installer scope but expands the trust surface.

Install Mechanism

There is no packaged install spec (instruction-only). The runtime steps contain multiple remote-install commands that fetch and run scripts (Homebrew raw install from GitHub, NodeSource setup script, and especially curl -fsSL https://astral.sh/uv/install.sh | sh). Running curl|sh from third-party domains (astral.sh) or raw scripts introduces higher risk because arbitrary code is executed locally. Cloning the GitHub repo and using make is expected, but any remote script piped to shell should be reviewed manually before execution.

Credentials

The skill itself does not declare required env vars in metadata, but the instructions clearly require model API keys and show env-variable placeholders for OpenAI, Anthropic, etc. Those credentials are proportionate to the stated purpose (configuring model backends). However the metadata not listing required env vars means the platform won't surface these secrets automatically — the user will need to provide them manually. The skill does not request unrelated cloud/provider credentials.

Persistence & Privilege

always:false and there is no code that tries to persist or alter other skills. The skill is user-invocable and can be invoked autonomously (default), which is normal. It does instruct creating files under the chosen INSTALL_DIR (~/deer-flow), which is expected for an installer.

Scan Findings in Context

[no_regex_findings] expected: The static regex scanner found no code files to analyze; this skill is instruction-only (SKILL.md) so the scanner had nothing to inspect. The main risk comes from commands in SKILL.md (remote install scripts), which static scanning did not flag because there are no local code files.

What to consider before installing

This skill appears to implement what it claims (DeerFlow installer/manager) but it runs remote installers and expects API keys — treat it like any third-party install script. Before running: 1) Verify the upstream repository (git clone URL) and inspect the repo contents (especially any install scripts and Makefile) rather than blindly piping curl to sh. 2) Avoid running scripts from unknown domains (e.g., astral.sh) without review; replace with packaged installs from your OS vendor where possible. 3) Provide API keys only into a config you control; consider using ephemeral or limited-scope keys and avoid committing secrets to repo. 4) Prefer running initial provisioning inside an isolated VM or container, not on a critical host. 5) If you need higher assurance, request the skill author/publisher and a homepage or upstream repo link and verify maintainer authenticity. If you’re uncomfortable with remote scripts or secret handling, perform a manual, audited installation following the commands shown rather than allowing automated execution.

DeerFlow 2.0 管理技能

本技能用于管理 DeerFlow 2.0 的完整生命周期：安装、配置、更新、卸载、启动。

使用场景

1. 首次安装 DeerFlow 2.0
2. 配置或更换大模型
3. 更新 DeerFlow 到最新版本
4. 卸载 DeerFlow
5. 排查启动问题

---

第一步：收集大模型配置信息

在开始安装前，需要向用户收集大模型配置信息。

询问用户

你好！在安装 DeerFlow 2.0 之前，我需要确认大模型配置。请提供以下信息：

1. 模型来源：你想使用哪个大模型？

   • OpenCode Zen big-pickle（免费，无需 API Key）
   • OpenAI（GPT-4o, GPT-4o-mini 等）
   • Anthropic（Claude 3.5 Sonnet 等）
   • Google（Gemini 2.5 Pro 等）
   • DeepSeek
   • Ollama（本地模型）
   • 其他 OpenAI 兼容接口

2. API 信息（根据选择的模型）：

   • API Key（如需要）
   • API Base URL（如使用第三方接口）
   • 模型名称

配置模板

根据用户选择，按以下模板配置 config.yaml 中的 models 部分：

OpenCode Zen big-pickle（免费）

models:
  - name: big-pickle
    display_name: Big Pickle (OpenCode Zen)
    use: langchain_openai:ChatOpenAI
    model: big-pickle
    api_key: ""
    base_url: https://opencode.ai/zen/v1
    request_timeout: 600.0
    max_retries: 2
    max_tokens: 8192

OpenAI

models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    request_timeout: 600.0
    max_retries: 2
    max_tokens: 4096

Claude

models:
  - name: claude-3-5-sonnet
    display_name: Claude 3.5 Sonnet
    use: langchain_anthropic:ChatAnthropic
    model: claude-sonnet-4-20250514
    api_key: $ANTHROPIC_API_KEY
    default_request_timeout: 600.0
    max_retries: 2

Ollama 本地模型

models:
  - name: qwen3-local
    display_name: Qwen3 32B (Ollama)
    use: langchain_ollama:ChatOllama
    model: qwen3:32b
    base_url: http://localhost:11434
    num_predict: 8192
    temperature: 0.7

---

第二步：安装流程

1. 检测操作系统

# 检测操作系统类型
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
echo "Detected OS: $OS"

2. 环境检测

echo "=== Node.js ===" && node --version
echo "=== pnpm ===" && pnpm --version
echo "=== uv ===" && uv --version
echo "=== Python ===" && python3 --version
echo "=== nginx ===" && nginx -v
echo "=== Docker ===" && docker --version
echo "=== Git ===" && git --version
echo "=== make ===" && make --version

3. 依赖安装（按系统）

macOS:

# 安装 Homebrew（如未安装）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖
brew install node pnpm uv python@3.12 nginx git make

Linux (Ubuntu/Debian):

# 安装系统依赖
sudo apt update
sudo apt install -y curl git make nginx python3.12 python3-pip

# 安装 Node.js 和 pnpm
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
npm install -g pnpm

# 安装 uv
curl -fsSL https://astral.sh/uv/install.sh | sh

Windows (WSL2 推荐):

# 使用 WSL2 或 PowerBox
# 推荐在 WSL2 Ubuntu 环境下安装
wsl --install -d Ubuntu

4. 安装步骤

# 1. 确定安装目录
INSTALL_DIR="$HOME/deer-flow"

# 2. 克隆仓库
git clone https://github.com/bytedance/deer-flow.git "$INSTALL_DIR"
cd "$INSTALL_DIR"

# 3. 创建配置文件
cp .env.example .env
cp config.example.yaml config.yaml

# 4. 编辑 config.yaml，添加模型配置
# 使用第一步收集的信息，编辑 config.yaml 中的 models 部分

# 5. 安装依赖
make check
make install

5. 验证安装

cd "$INSTALL_DIR"
make doctor

6. 启动服务

cd "$INSTALL_DIR"
make dev

服务启动后，访问 **http://localhost:2026**。

---

第三步：更新流程

# 确定安装目录
INSTALL_DIR="$HOME/deer-flow"

cd "$INSTALL_DIR"

# 1. 拉取最新代码
git pull origin main

# 2. 合并新配置字段
make config-upgrade

# 3. 重建 venv
cd backend && rm -rf .venv && uv sync && cd ..

# 4. 重新安装依赖
make install

---

第四步：卸载流程

# 确定安装目录
INSTALL_DIR="$HOME/deer-flow"

cd "$INSTALL_DIR"

# 1. 停止服务
make stop

# 2. 清理临时文件
make clean

# 3. 删除目录
rm -rf "$INSTALL_DIR"

---

第五步：常见问题排查

LangGraph 启动卡住

问题：LangGraph 服务启动在 2024 端口等待超时。

原因：可能是 venv 路径问题（项目迁移后 shebang 失效）。

解决：

cd "$INSTALL_DIR/backend"
rm -rf .venv
uv sync
cd ..
make dev

模型连接失败

问题：大模型 API 调用失败。

排查：

1. 检查 config.yaml 中的模型配置是否正确
2. 检查 API Key 是否有效（环境变量或直接填写）
3. 检查 base_url 是否可访问

端口被占用

问题：2024/8001/3000/2026 端口被占用。

排查：

# Linux/macOS
lsof -i :2024
lsof -i :2026

# Windows
netstat -ano | findstr "2024"

解决：停止占用进程或修改 config.yaml 中的端口配置。

---

输出常用命令表格

在完成安装或更新后，向用户输出以下常用命令表格：

---

🦌 DeerFlow 2.0 常用命令速查表

📦 安装与初始化

命令	说明	场景
make setup	交互式安装向导（推荐新手）	首次安装引导
make check	检查系统依赖是否齐全	安装前验证
make install	安装前后端全部依赖	手动安装依赖
make config	生成配置文件（需手动编辑）	高级用户手动配置
make config-upgrade	合并模板新字段到现有配置	配置升级
make doctor	检查配置和系统要求	诊断问题
make setup-sandbox	预拉取沙箱容器镜像	Docker 模式准备

🚀 启动与运行

命令	说明	端口	场景
make dev	开发模式（热重载）	localhost:2026	本地开发（推荐）
make dev-pro	开发模式 + Gateway	localhost:2026	实验特性
make dev-daemon	后台开发模式	localhost:2026	守护进程
make start	生产模式（无热重载）	localhost:2026	正式运行
make start-pro	生产模式 + Gateway	localhost:2026	实验特性
make start-daemon	后台生产模式	localhost:2026	守护进程

⏹ 停止与管理

命令	说明
make stop	停止所有运行中的服务
make clean	停止服务��清理临时文件

🐳 Docker 模式

命令	说明	场景
make up	构建并启动生产 Docker	生产部署（推荐）
make up-pro	生产 Docker + Gateway	实验特性
make down	停止并移除容器	清理

⚙️ 配置文件位置

文件	说明
config.yaml	主配置文件（模型、工具、沙箱等）
.env	环境变量（API Keys）
logs/	运行日志目录

🔌 服务端口映射

服务	端口	说明
LangGraph	2024	Agent 运行时
Gateway	8001	REST API
Frontend	3000	Next.js 前端
Nginx	2026	反向代理（主入口）

---

快速启动

cd ~/deer-flow && make dev

访问 http://localhost:2026 即可使用 DeerFlow 2.0。

---

文件位置（动态获取）

• 安装目录：~/deer-flow/
• 配置文件：~/deer-flow/config.yaml
• 环境变量：~/deer-flow/.env
• 日志目录：~/deer-flow/logs/

详细命令参考见 references/deer-flow-commands.md。