电脑里刚 clone 完一个 AI Agent 项目，终端下一秒就问你模型、搜索工具、sandbox 权限和 Docker，要是没有顺序，很容易卡在“配置文件缺失”或“服务启动了但模型不能用”。安装 DeerFlow 的顺序其实不复杂：先把仓库和配置准备好，再决定用 Docker 跑，还是走本地开发环境。

先弄清 DeerFlow 能做什么

DeerFlow 是 ByteDance 开源的 AI Agent 工作流项目，当前主线是 DeerFlow 2.0。它不是单个聊天机器人，而是把 sub-agents、memory、skills、tools 和 sandbox 组织在一起，让一个任务可以分解、执行、写文件、调用工具，再把结果收回来。能做的是长任务编排，比如深度研究、代码生成、报告整理、内容工作流和带文件系统的自动化执行。

不能做的是“装完就自动替你完成所有事”。模型密钥、搜索工具、sandbox 权限和本机资源都要自己确认。失败场景通常长这样：页面能打开，但一发任务就报 provider 找不到；或者 agent 准备写文件时，sandbox 没配置好，任务停在执行前。

安装前先准备这三件事

第一，准备 Git 和一个可用的终端。第二，准备模型访问方式，可以是 OpenAI 兼容接口、OpenRouter、本地 vLLM、Codex CLI 或 Claude Code OAuth 等配置。第三，选择运行方式：如果机器已经有 Docker，优先走 Docker；如果想直接调试前后端，再走本地开发。

资源上不要太紧。轻量本地体验至少按 4 vCPU、8 GB 内存和 20 GB 可用空间准备；Docker 开发最好再多留一点磁盘空间。失败场景是机器只有 2 核 4 GB，服务虽然能拉起来，但多个 agent 或 sandbox 任务一跑，CPU 和内存一起打满，表现像“程序坏了”，实际是资源不够。

推荐安装路径：先跑 make setup

在终端执行下面几步：

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

make setup 是官方推荐的安装向导，会引导选择 LLM provider、可选 web 搜索工具，以及 sandbox、bash 权限、文件写入等偏好，并生成最小化的 config.yaml，同时把 API key 写入 .env。之后跑 make doctor，它会检查配置和系统环境，并给出可执行的修复建议。

这里能做的是把安装从“手改一堆文件”变成向导式配置。不能做的是替你凭空生成真实密钥。失败场景是一路回车跳过模型配置，最后启动页面没有问题，但发任务时才发现没有任何可调用模型。

Docker 方式：少折腾本机依赖

如果 Docker 已经安装并且 daemon 正在运行，用这组命令更省事：

make docker-init
make docker-start

make docker-init 主要准备 Docker 开发环境和 sandbox 镜像；make docker-start 才是启动服务。服务起来后，浏览器访问 http://localhost:2026。这条路适合只想体验 DeerFlow 工作流、不想在本机逐个处理 Node、pnpm、uv、nginx 依赖的人。

它的失败场景也清楚：Docker Desktop 没启动，命令会卡在连接 daemon；第一次拉镜像速度慢，看起来像无响应；或者 2026 端口被别的服务占用，页面打不开。遇到这些问题，先查 Docker 状态和端口，不要急着改 DeerFlow 配置。

本地开发方式：适合改代码和看细节

如果你要改前端、后端或研究 DeerFlow 的 agent loop，用本地开发路径：

make check
make install
make setup-sandbox
make dev

make check 会检查 Node.js 22+、pnpm、uv、nginx 等依赖；make install 安装 backend 和 frontend 依赖；如果配置了 Docker/Container sandbox，建议先跑 make setup-sandbox 预拉镜像，避免第一次执行 agent 时等太久。最后用 make dev 启动，访问地址同样是 http://localhost:2026。

这条路能让你更直接地调试源码，但不能省掉系统依赖。失败场景是 make check 已经提示缺 pnpm 或 nginx，还继续执行 make dev，最后看到一串端口、代理或构建错误。

启动后怎么用 AI Agent 工作流

打开 Web UI 后，先用小任务测试，不要一上来丢一个小时级别的研究任务。可以先让它整理一个公开资料摘要、生成一个小脚本，或让它读一段文档后输出检查清单。观察三件事：模型是否能响应，工具是否能调用，sandbox 是否能写入和读取文件。

DeerFlow 的核心价值在“让 agent 把事情做完”：skills 用来定义能力，tools 用来连接搜索、抓取、截图、文件和 bash，sub-agents 用来拆分复杂任务，memory 用来保留长期偏好。失败场景是把它当普通问答窗口用，只问一句泛泛的问题，最后得到的也只是泛泛回答；更好的用法是交代目标、输入材料、输出格式和验收标准。

最后按这张清单验收

安装完成后，至少确认五件事：项目根目录有 config.yaml；.env 或 shell 里有真实 API key；make doctor 没有阻断项；浏览器能打开 http://localhost:2026；一次简单任务能开始执行并返回结果。少一项都不算完整安装。

如果你只想最快跑起来，路径是 git clone、make setup、make doctor、make docker-init、make docker-start。如果你要研究 ByteDance 这个 AI Agent 工作流的源码和扩展机制，再切到本地开发。先把入口跑通，再谈复杂工作流，排错成本会低很多。