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 [email protected] 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 常用命令速查表

📦 安装与初始化

🚀 启动与运行

⏹ 停止与管理

🐳 Docker 模式

⚙️ 配置文件位置

🔌 服务端口映射

快速启动

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。