DeerFlow 2.0 入门教程：手把手搭建你的第一个 AI Agent 工作站

难度入门 | 时长 15 分钟 | 收获零基础搭建可执行 AI 助手

你是否曾想过，如果有一个 AI 助手不仅能回答问题，还能真正帮你操作电脑、写代码、搜索信息、甚至生成完整的报告，那会怎样？今天我们要介绍的 DeerFlow，就是这样一个能帮你干活的 AI Agent。

目标读者

1-3 年后端/全栈开发者
对 AI Agent 感兴趣但不知从何入手
想自托管 AI 工具又担心成本

核心依赖与环境

在开始之前，确保你的开发环境满足以下要求：

Node.js：22.x 或更高版本
pnpm：9.x 或更高版本
Docker：最新稳定版
Git：用于克隆项目

[!TIP]
推荐使用 Docker 方式部署，一键启动，无需手动配置 Nginx 等服务。

完整项目结构

安装完成后，你会看到如下项目结构：

deer-flow/
├── backend/                    # 后端服务
│   ├── src/
│   │   ├── client.py           # Python 客户端
│   │   ├── agent/              # Agent 核心
│   │   └── skills/            # 内置技能
│   └── docs/                   # 配置文档
├── frontend/                   # Web 界面
├── config.yaml                 # 模型配置文件
├── .env                        # 环境变量
└── Makefile                    # 启动命令

手把手步骤

第 1 步：克隆项目

打开终端，执行以下命令：

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

[!TIP]
如果你访问 GitHub 有困难，可以考虑使用镜像源，或者直接下载 Release 版本的压缩包。

第 2 步：生成配置文件

DeerFlow 提供了配置生成命令，会基于模板创建本地配置文件：

make config

执行后，你会发现项目根目录多了 config.yaml 和 .env 文件。

第 3 步：配置模型（重点！）

这是最关键的一步。DeerFlow 支持多种模型供应商，但我们强烈推荐使用 Defapi，原因很简单：价格只有官方的一半。

[!WARNING]
如果你直接使用 OpenAI 官方 API，每月费用可能轻松超过几百美元。使用 Defapi 可以把这个成本降到一半甚至更低。

打开 config.yaml，配置如下：

models:
  - name: gpt-4o-mini              # 内部标识符
    display_name: GPT-4o Mini      # 显示名称
    use: langchain_openai:ChatOpenAI
    model: openai/gpt-4o-mini      # Defapi 模型标识
    api_key: $DEFAPI_API_KEY       # 使用环境变量
    base_url: https://api.defapi.org  # Defapi 端点
    max_tokens: 4096
    temperature: 0.7
    supports_vision: true

然后在 .env 文件中填入你的 Defapi API Key：

DEFAPI_API_KEY="dk-xxxxxxxxxxxxxxxx"
TAVILY_API_KEY="your-tavily-api-key"  # 用于网页搜索

[!TIP]
访问 https://defapi.org 注册账号，新用户有免费额度可以先体验。

Defapi 支持的热门模型：

模型	标识符	适用场景
GPT-4o Mini	openai/gpt-4o-mini	日常对话，性价比高
GPT-4o	openai/gpt-4o	复杂任务，平衡之选
Claude Sonnet 4.5	anthropic/claude-sonnet-4.5	编程能力强
DeepSeek V3	deepseek/deepseek-v3	推理能力强，价格便宜

第 4 步：拉取沙箱镜像

Docker 方式运行前，需要先拉取沙箱镜像（这一步只需要执行一次）：

make docker-init

镜像比较大，可能需要等待几分钟。

第 5 步：启动服务

一切就绪，启动 DeerFlow：

make docker-start

看到类似这样的输出就说明启动成功了：

✔ Frontend started on http://localhost:2026
✔ Backend started on http://localhost:8000

第 6 步：访问界面

打开浏览器，访问 **http://localhost:2026**，你会看到一个现代化的聊天界面。

第 7 步：第一个任务

在聊天框中输入：

你好，请介绍一下你自己

你会发现 DeerFlow 不仅会回答你，还会告诉你它有哪些能力：

搜索网页
读写文件
执行命令
生成报告、幻灯片、网页

再试试一个更有挑战性的任务：

请列出当前目录的文件结构

DeerFlow 会在沙箱环境中执行命令，并返回结果。这就是它和普通聊天机器人的本质区别——它真的能帮你干活。

常见问题排查

Q1：容器启动失败，提示端口被占用

# 查看哪个进程占用了 2026 端口
lsof -i :2026
# 或者
netstat -ano | findstr 2026

找到后 kill 掉，或者修改 config.yaml 中的端口。

Q2：API Key 配置正确但还是报错

检查 .env 文件是否在项目根目录，并且执行了 source .env 或重启容器。

Q3：模型不支持工具调用

有些模型不支持 function calling。请确保使用的是 GPT-4o、Claude、Gemini 等支持工具调用的模型。Defapi 提供的模型都是兼容 OpenAI 协议的，一般没问题。

Q4：网页搜索返回空结果

检查 TAVILY_API_KEY 是否配置正确。Tavily 是 DeerFlow 默认的搜索provider。

Q5：Docker 内存不足

Docker 默认内存可能不够，建议设置 4GB 以上：

// Docker Desktop -> Settings -> Resources

Q6：想用本地开发模式

如果不想用 Docker，也可以本地运行：

make check    # 检查环境
make dev      # 启动开发服务

进阶方向

1. 自定义 Skills

DeerFlow 的 Skills 系统非常灵活。你可以创建自己的 Skill：

/mnt/skills/custom/
└── my-awesome-skill/
    └── SKILL.md

参考内置 Skill 的格式编写 Markdown 文件即可。

2. MCP 服务器扩展

DeerFlow 支持 MCP 协议，可以接入各种外部工具。详见官方文档 MCP Server Guide。

3. 切换到其他模型

如果你想尝试 DeepSeek 或 Claude，只需要修改 config.yaml：

# DeepSeek 配置示例
models:
  - name: deepseek-v3
    display_name: DeepSeek V3
    use: langchain_openai:ChatOpenAI
    model: deepseek/deepseek-v3
    api_key: $DEFAPI_API_KEY
    base_url: https://api.defapi.org
    supports_thinking: true

4. 使用嵌入式 Python 客户端

DeerFlow 还提供了 Python 库，可以直接嵌入到你的项目中：

from src.client import DeerFlowClient

client = DeerFlowClient()
response = client.chat("分析这篇论文", thread_id="my-thread")

# 流式输出
for event in client.stream("hello"):
    print(event.data)

总结

今天我们一起搭建了 DeerFlow 2.0，从环境准备到启动服务，再到第一个任务。你会发现，这不仅仅是一个聊天机器人，而是一个真正能帮你干活的 AI 工作站。

DeerFlow 的核心优势在于：

可扩展：Skills、MCP、Sub-Agents 都支持自定义
安全可控：沙箱隔离，任务在 Docker 容器中运行
成本灵活：通过 Defapi 可以把成本降到官方的一半

快去试试吧！让它帮你写代码、搜索信息、生成报告。你会发现 AI 还能这样用。

如果你在搭建过程中遇到问题，欢迎在评论区留言，我会尽量帮你解答。下次我们会深入讲讲如何自定义 Skills，让 DeerFlow 完成特定任务。

祝玩得开心！