DeerFlow Windows 本地运行教程（uv）

项目路径：h:\deerflow\deer-flow-main

Python 管理：全程 uv（不直接用系统 python）

无需 make / git / nginx，手动双终端启动

一、工具安装

1. 安装 uv（Python 包管理器）

uv 是 Astral 出品的极速 Python 包管理器，替代 pip / venv / pip-tools。DeerFlow 后端用它管理依赖，本教程所有 python 调用都走 uv。

方式一：官方安装脚本（推荐）

打开 PowerShell：

powershell 复制代码

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

方式二：Scoop

powershell 复制代码

scoop install uv

方式三：pip（已有 python 环境时）

powershell 复制代码

pip install uv

安装后重启终端，验证：

powershell 复制代码

uv --version

uv 常用命令：

powershell 复制代码

uv python install 3.12      # 安装 Python 3.12（DeerFlow 要求 ≥3.12）
uv sync                      # 按 pyproject.toml + uv.lock 同步依赖（自动建虚拟环境 + 装 Python）
uv run <command>             # 在项目虚拟环境中运行命令（本教程核心）
uv add <package>             # 添加依赖

DeerFlow 后端 backend/.python-version 指定 3.12，uv sync 会自动下载安装对应 Python，无需手动装 Python。

2. 安装 Node.js + pnpm

Node.js 22+：https://nodejs.org/ 下载 LTS 安装

pnpm 10.26.2+：

powershell 复制代码

npm install -g pnpm@10.26.2
# 或用 corepack（Node.js 自带）
corepack enable

验证：

powershell 复制代码

node -v    # v22.x.x
pnpm -v    # 10.26.x

二、安装后端依赖（建立 uv 环境）

uv sync 会创建虚拟环境、安装 Python 3.12、装好后端全部依赖。不需要 config.yaml，纯粹装依赖。

powershell 复制代码

cd h:\deerflow\deer-flow-main\backend
uv sync

国内加速（可选，慢的话先设镜像再 sync）：

PowerShell：

powershell 复制代码

$env:UV_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"
uv sync

CMD：

cmd 复制代码

set UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
uv sync

注意：set / $env: 只对当前窗口有效；永久生效用 setx UV_INDEX_URL "https://pypi.tuna.tsinghua.edu.cn/simple"（设完重开终端）。
完成后 backend\.venv\ 虚拟环境就建好了，后续所有 uv run 都在这个环境里跑。

三、生成配置文件

环境已就绪，现在用 uv run 生成配置。所有 python 脚本都从 backend 目录用 uv run 调用。

powershell 复制代码

cd h:\deerflow\deer-flow-main\backend
uv run python ..\scripts\configure.py

生成三个文件（在项目根目录 h:\deerflow\deer-flow-main\）：

文件	作用
`config.yaml`	主配置（模型、沙箱、通道等）
`.env`	API Key 等密钥
`frontend\.env`	前端配置

四、配置模型与 API Key

1. 编辑 `config.yaml`，在 `models:` 下添加至少一个模型

OpenAI

yaml 复制代码

models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY
    context_window: 128000
    supports_vision: true

DeepSeek

yaml 复制代码

models:
  - name: deepseek-chat
    display_name: DeepSeek Chat
    use: langchain_openai:ChatOpenAI
    model: deepseek-chat
    api_key: $DEEPSEEK_API_KEY
    base_url: https://api.deepseek.com/v1
    context_window: 64000

火山引擎豆包（国内推荐）

yaml 复制代码

models:
  - name: doubao-seed
    display_name: Doubao Seed
    use: deerflow.models.patched_deepseek:PatchedChatDeepSeek
    model: doubao-seed-1-8-251228
    api_base: https://ark.cn-beijing.volces.com/api/v3
    api_key: $VOLCENGINE_API_KEY
    context_window: 262144
    supports_thinking: true

OpenRouter（一个 Key 接多家模型）

yaml 复制代码

models:
  - name: gemini-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1

2. 编辑 `.env` 填入对应 API Key

bash 复制代码

OPENAI_API_KEY=sk-xxxx
# 或
DEEPSEEK_API_KEY=sk-xxxx
# 或
VOLCENGINE_API_KEY=xxxx
# 或
OPENROUTER_API_KEY=sk-or-xxxx

# 可选：搜索工具（填一个即可，不填也能用，只是没联网搜索）
TAVILY_API_KEY=your-tavily-api-key
# SERPER_API_KEY=your-serper-api-key
# JINA_API_KEY=your-jina-api-key

3. 编辑 `frontend\.env`

取消注释这两行（手动启动方式必须配置）：

bash 复制代码

NEXT_PUBLIC_BACKEND_BASE_URL="http://localhost:8001"
NEXT_PUBLIC_LANGGRAPH_BASE_URL="http://localhost:8001/api"

4. 启用智能体功能（可选）

DeerFlow 有两类智能体，开启方式不同：

A. 自定义智能体管理（侧边栏"智能体"菜单）

控制 Web 界面侧边栏是否显示"智能体"菜单，开启后可在 UI 里创建/管理自定义智能体（名称、模型、工具组、技能、人格 soul 等）。

在 config.yaml 中：

yaml 复制代码

agents_api:
  enabled: true    # 默认 false，改成 true 开启

开启后效果：

后端 Gateway 暴露 /api/agents 管理接口
前端侧边栏出现可点击的"智能体"菜单（机器人图标）
进入 http://localhost:3000/workspace/agents 页面即可自定义智能体

改完 config.yaml 重启后端 即可，前端无需重新打包（页面挂载时自动重新查询开关状态）。

安全提示：该 API 涉及自定义 agent 的 SOUL/USER.md 写入，官方注释建议仅在可信认证边界后开启。本地自用没问题。

B. 对话内子智能体委派（Ultra 模式）

在聊天对话中让主智能体把任务拆分委派给子智能体执行。绑定到对话模式，切到 "Ultra" 模式自动启用，无需改配置。

在聊天输入框的模式选择器里选 "Ultra"：

模式	thinking	planning	subagent	reasoning	适用场景
flash	✗	✗	✗	---	快速回答
thinking	✓	✗	✗	默认	需要思考
pro	✓	✓	✗	默认	规划+执行
ultra	✓	✓	✓	high	复杂多步任务

前端构造请求时底层逻辑：

typescript 复制代码

subagent_enabled: context.mode === "ultra"

可选调优：如需调整子智能体超时、并发、自定义子智能体类型，在 config.yaml 取消注释 subagents: 配置块按需调整（默认注释掉，用内置默认值即可正常运行）。

五、安装前端依赖

powershell 复制代码

cd h:\deerflow\deer-flow-main\frontend
pnpm install

国内加速（可选）：

powershell 复制代码

pnpm config set registry https://registry.npmmirror.com
pnpm install

六、验证配置健康

所有依赖装完、配置填好后，跑一次体检：

powershell 复制代码

cd h:\deerflow\deer-flow-main\backend
uv run python ..\scripts\doctor.py

检查 config.yaml、API Key、依赖完整性，缺啥报啥。

七、启动服务（手动双终端）

终端 1 --- 后端 Gateway：

powershell 复制代码

cd h:\deerflow\deer-flow-main\backend
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload

终端 2 --- 前端 Next.js：

powershell 复制代码

cd h:\deerflow\deer-flow-main\frontend
pnpm dev

访问：http://localhost:3000

首次访问会跳转 /setup 创建管理员账号。

停止：对应终端按 Ctrl+C。

八、常见问题

Q: `uv sync` 报错或很慢

国内镜像：

PowerShell：

powershell 复制代码

$env:UV_INDEX_URL = "https://pypi.tuna.tsinghua.edu.cn/simple"
uv sync

CMD：

cmd 复制代码

set UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
uv sync

Q: 端口被占用

powershell 复制代码

# 查看占用 8001 端口的进程
netstat -ano | findstr :8001
# 杀掉对应 PID
taskkill /PID <PID> /F

Q: Agent 无法执行 shell 命令

默认沙箱 LocalSandboxProvider 禁用 host bash（安全考虑）。在 config.yaml 中开启：

yaml 复制代码

sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
  allow_host_bash: true   # 仅信任的本地环境开启

Q: 前端页面打不开 / 报 403 / 无法登录

确认 frontend\.env 已取消注释 NEXT_PUBLIC_BACKEND_BASE_URL 和 NEXT_PUBLIC_LANGGRAPH_BASE_URL。

Q: Python 版本不对

powershell 复制代码

cd h:\deerflow\deer-flow-main\backend
uv python install 3.12
uv python pin 3.12

Q: `uv: command not found`

安装 uv 后需重启终端。检查：

powershell 复制代码

where.exe uv

Q: 前端依赖装不上

powershell 复制代码

cd h:\deerflow\deer-flow-main\frontend
pnpm config set registry https://registry.npmmirror.com
pnpm install

九、服务端口说明

服务	端口	说明
Gateway API	8001	后端 FastAPI + Agent 运行时
Frontend	3000	Next.js 前端（浏览器访问）

十、命令速查表

所有 python 脚本统一从 backend 目录用 uv run 调用。

操作	命令
安装后端依赖	`cd backend` → `uv sync`
生成配置	`cd backend` → `uv run python ..\scripts\configure.py`
配置体检	`cd backend` → `uv run python ..\scripts\doctor.py`
检查工具依赖	`cd backend` → `uv run python ..\scripts\check.py`
安装前端依赖	`cd frontend` → `pnpm install`
启动后端	`cd backend` → `uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload`
启动前端	`cd frontend` → `pnpm dev`
安装 Python 3.12	`uv python install 3.12`

十一、最小启动流程（TL;DR）

powershell 复制代码

# ===== 第一步：装工具 =====
# uv（见第一节）
# Node.js 22+ + pnpm 10.26.2+

# ===== 第二步：装后端依赖（建立 uv 环境）=====
cd h:\deerflow\deer-flow-main\backend
uv sync

# ===== 第三步：生成配置文件 =====
uv run python ..\scripts\configure.py

# ===== 第四步：编辑配置 =====
# 编辑 h:\deerflow\deer-flow-main\config.yaml 加模型
# 编辑 h:\deerflow\deer-flow-main\.env 加 API Key
# 编辑 h:\deerflow\deer-flow-main\frontend\.env 取消注释两行 BACKEND_URL

# ===== 第五步：装前端依赖 =====
cd ..\frontend
pnpm install

# ===== 第六步：验证配置 =====
cd ..\backend
uv run python ..\scripts\doctor.py

# ===== 第七步：启动（两个终端）=====
# 终端1 - 后端:
cd h:\deerflow\deer-flow-main\backend
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload

# 终端2 - 前端:
cd h:\deerflow\deer-flow-main\frontend
pnpm dev

# ===== 第八步：浏览器访问 http://localhost:3000，创建管理员账号 =====

DeerFlow Windows 本地运行教程（uv）