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 兼容接口

1. 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 常用命令速查表

📦 安装与初始化

🚀 启动与运行

⏹ 停止与管理

🐳 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。