← 返回文章列表

DeerFlow 2.0 配置与使用指南

2026/4/7

DeerFlow 2.0 配置与使用指南

本地部署的 AI Agent 系统，通过 MCP（Model Context Protocol）与 WorkBuddy 连接

官方仓库：https://github.com/DeerFlowTeam/DeerFlow

最后更新：2026-04-07

一、系统架构

DeerFlow 2.0 由多个服务组成：

服务端口说明
Gateway API8000线程管理、消息收发
LangGraph API8001AI 对话流引擎
MCP Server8002WorkBuddy 集成接口

二、安装步骤

2.1 环境准备

# 使用 WSL Ubuntu
wsl -d Ubuntu

# 创建并激活虚拟环境
python3 -m venv ~/deerflow-env
source ~/deerflow-env/bin/activate

2.2 安装 DeerFlow

cd /mnt/c/Users/25775/deer-flow
pip install -e ".[long-memory]"

2.3 配置文件

主配置文件位于项目根目录，主要环境变量：

# .env 或系统环境变量
LANGGRAPH_BASE=http://127.0.0.1:8001/api      # LangGraph API 地址
LANGGRAPH_ASSISTANT_ID=lead_agent              # 默认 assistant ID

三、启动服务

3.1 启动脚本

项目根目录已包含 start-mcp.sh：

cd /mnt/c/Users/25775/deer-flow
bash start-mcp.sh

脚本内容：

#!/bin/bash
cd /mnt/c/Users/25775/deer-flow
source /home/user/deerflow-env/bin/activate
nohup uvicorn deerflow_mcp_server:app --host 0.0.0.0 --port 8002 > /tmp/deerflow-mcp.log 2>&1 &
echo "MCP Server PID: $!"

3.2 验证服务状态

# 检查 MCP Server 健康状态
curl http://127.0.0.1:8002/health

# 查看运行日志
tail -f /tmp/deerflow-mcp.log

# 查看进程
ps aux | grep deerflow

3.3 停止服务

pkill -f "uvicorn deerflow_mcp_server"

四、MCP 工具接口

4.1 可用工具

工具名称功能
create_session创建新会话
search_sessions搜索历史会话
delete_session删除会话
send_messages_to_user发送用户消息并获取 AI 回复

4.2 工具参数说明

create_session

{
    "user_id": "string",      # 用户标识
    "assistant_id": "string"  # 可选，默认 "lead_agent"
}

send_messages_to_user

{
    "session_id": "string",   # 会话 ID
    "content": "string"       # 用户输入内容
}

五、API 路径参考

5.1 Gateway 线程接口

方法路径功能
POST/api/threads创建新线程
POST/api/threads/search搜索线程
DELETE/api/threads/{id}删除线程
GET/api/threads/{id}/messages获取消息历史

5.2 LangGraph Runs 流接口

POST /api/threads/{thread_id}/runs/stream
LANGGRAPH_BASE = http://127.0.0.1:8001/api

5.3 默认配置

  • 默认 assistant_id: lead_agent
  • 默认模型: MiniMax-M2.7

六、WorkBuddy 集成配置

DeerFlow 已通过 MCP 协议与 WorkBuddy 集成，配置位于：

// ~/.workbuddy/mcp.json
{
    "mcpServers": {
        "deer-flow": {
            "command": "uvicorn",
            "args": ["deerflow_mcp_server:app", "--host", "0.0.0.0", "--port", "8002"],
            "cwd": "/mnt/c/Users/25775/deer-flow"
        }
    }
}

⚠️ 修改配置后需重启 WorkBuddy 使配置生效。

七、使用示例

7.1 基础对话

在 WorkBuddy 中直接说：

  • 「用 DeerFlow 帮我搜索今天的天气」
  • 「在 DeerFlow 里问：Python 如何实现斐波那契数列？」
  • 「创建一个叫 test 的 DeerFlow 线程」

7.2 手动测试对话

import requests

response = requests.post(
    "http://127.0.0.1:8002/send_messages_to_user",
    json={
        "session_id": "your-session-id",
        "content": "你好，请介绍一下你自己！"
    }
)
print(response.json())

八、常见问题

Q1: MCP Server 启动失败，端口被占用

# 查看端口占用
lsof -i :8002

# 杀死占用进程后重试
pkill -f "uvicorn"
bash start-mcp.sh

Q2: 消息发送成功但没有回复

检查 LangGraph 服务是否正常运行：

curl http://127.0.0.1:8001/health

Q3: 如何查看完整日志

# 实时查看日志
tail -f /tmp/deerflow-mcp.log

# 查看最近 100 行
tail -100 /tmp/deerflow-mcp.log

九、文件清单

文件路径说明
/mnt/c/Users/25775/deer-flow/start-mcp.shMCP Server 启动脚本
/tmp/deerflow-mcp.log运行日志
~/.workbuddy/mcp.jsonWorkBuddy MCP 配置