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（免费）

yaml

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

yaml

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

yaml

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 本地模型

yaml

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. 检测操作系统#

bash

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

2. 环境检测#

bash

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:

bash

# 安装 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):

bash

# 安装系统依赖
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 推荐):

bash

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

4. 安装步骤#

bash

# 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. 验证安装#

bash

cd "$INSTALL_DIR"
make doctor

6. 启动服务#

bash

cd "$INSTALL_DIR"
make dev

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

---

第三步：更新流程#

bash

# 确定安装目录
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

---

第四步：卸载流程#

bash

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

cd "$INSTALL_DIR"

# 1. 停止服务
make stop

# 2. 清理临时文件
make clean

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

---

第五步：常见问题排查#

LangGraph 启动卡住#

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

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

解决：

bash

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 端口被占用。

排查：

bash

# 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开发模式 + Gatewaylocalhost:2026实验特性make dev-daemon后台开发模式localhost:2026守护进程make start生产模式（无热重载）localhost:2026正式运行make start-pro生产模式 + Gatewaylocalhost: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/运行日志目录

🔌 服务端口映射

服务端口说明LangGraph2024Agent 运行时Gateway8001REST APIFrontend3000Next.js 前端Nginx2026反向代理（主入口）

---

快速启动#

bash

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。