ChatDev 教程：从零搭建你的多智能体自动化平台

小新软件平替发表于2026-05-22

你是否想过，让多个 AI 智能体像一支团队一样协作，自动完成数据可视化、3D 生成、深度调研甚至软件开发？ChatDev 2.0（代号 DevAll）正是为此而生。

ChatDev 是什么？ ChatDev 是由清华大学 THUNLP 实验室和 ModelBest 团队开发的开源多智能体编排平台。截至 2026 年 1 月发布的 2.0 版本（DevAll），它已从最初的”虚拟软件公司”概念演进为一个通用的零代码多智能体编排平台，用户无需编写代码即可通过 YAML 配置或 Web 控制台定义智能体、编排工作流并执行复杂任务。

ChatDev 已从最初的”虚拟软件公司”（1.0 版本）进化为一个通用的零代码多智能体编排平台。你不需要会写代码，只需通过可视化界面或 YAML 配置文件，就能定义智能体、编排工作流、执行复杂任务。

关键数据：

🌟 GitHub Stars: 3,300+（OpenBMB/ChatDev）
📅 2.0 发布日期：2026 年 1 月 7 日
⚖️ 许可证：Apache 2.0
🧠 支持模型：OpenAI、Anthropic、Gemini、Ollama 等任意 OpenAI 兼容接口
📦 内置示例：数据可视化、3D 生成、游戏开发、深度调研等

本文将带你从零开始，完成 ChatDev 2.0 的安装、配置和首次使用。

前提条件

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

操作系统：macOS / Linux / WSL / Windows（均支持）
Python：3.12 或更高版本
Node.js：18 或更高版本
包管理器：uv（Python 包管理工具，比 pip 更快）
LLM API：需要一个支持 OpenAI 兼容接口的 API（如 OpenAI、Anthropic、本地部署的 Ollama 等）

💡 提示：如果你没有 API Key，可以先使用 Ollama 在本地运行开源模型，完全免费。

概述

ChatDev 2.0 的核心架构由三部分组成：

后端服务：基于 FastAPI 的 Python 后端，负责解析 YAML 工作流、调度智能体执行
Web 控制台：基于 Vue 3 的前端界面，提供可视化工作流编辑和任务监控
工作流引擎：解析 YAML DAG（有向无环图），协调各个智能体节点的执行顺序

整个执行流程为：编写 YAML 配置 → 上传到平台 → 输入任务提示 → 智能体自动执行 → 输出结果。

关键特性：

零代码：通过 YAML 或 Web UI 定义工作流，无需编程
多智能体编排：支持 DAG 和循环图结构，可编排任意复杂的智能体协作
动态并行：Map/Tree 模式自动拆分和合并任务
人机协作：human 节点支持人工审核和干预
多模型支持：OpenAI、Gemini、Ollama 等任意 OpenAI 兼容接口
开源免费：Apache 2.0 许可证，GitHub 仓库

第一步：安装 ChatDev

克隆仓库

首先，将 ChatDev 仓库克隆到本地：

1 2	git clone https://github.com/OpenBMB/ChatDev.git cd ChatDev

安装后端依赖

ChatDev 2.0 使用 uv 作为 Python 包管理器，安装速度远快于 pip：

uv sync

这条命令会自动读取项目中的 pyproject.toml，安装所有 Python 依赖。

安装前端依赖

ChatDev 的 Web 控制台基于 Vue 3 + Vite 构建：

1	cd frontend && npm install

安装完成后返回项目根目录。

第二步：配置 API 密钥

ChatDev 需要一个 LLM API 来驱动智能体。配置方法非常简单：

1	cp .env.example .env

然后编辑 .env 文件，填入你的 API 信息：

1
2
3

# 示例配置
API_KEY=sk-your-api-key-here
BASE_URL=https://api.openai.com/v1

💡 提示：ChatDev 使用 OpenAI 兼容接口，这意味着几乎所有主流 LLM 提供商都能用——OpenAI、Anthropic、Google Gemini、本地 Ollama 等，只要它们支持 /v1/chat/completions 接口。

你也可以在 YAML 工作流中使用 ${VAR} 占位符引用环境变量，例如：

1
2
3

vars:
  API_KEY: ${API_KEY}
  BASE_URL: ${BASE_URL}

第三步：启动 ChatDev

方式一：使用 Makefile（推荐）

ChatDev 提供了 Makefile 一键启动前后端：

make dev

启动后，访问 http://localhost:5173 即可打开 Web 控制台。

方式二：手动启动

如果你需要更细粒度的控制，可以分别启动前后端：

启动后端：

1	uv run python server_main.py --port 6400 --reload

启动前端：

1 2	cd frontend VITE_API_BASE_URL=http://localhost:6400 npm run dev

💡 提示：如果端口 6400 被占用，可以更换为其他端口，例如 --port 6401，同时前端设置 VITE_API_BASE_URL=http://localhost:6401。

方式三：使用 Docker

如果你更倾向于容器化部署：

1	docker compose up --build

Docker 方式会自动处理所有依赖，适合生产环境部署。

第四步：使用 Web 控制台创建第一个工作流

现在让我们通过 Web 控制台创建一个简单的工作流。

1. 进入 Launch 视图

访问 http://localhost:5173，在左侧导航栏点击 Launch View。

2. 选择工作流

左侧面板列出了所有可用的工作流 YAML 文件（位于 yaml_instance/ 目录）。首次使用时，你可以选择内置的 demo.yaml 作为起点。

3. 输入任务提示

在文本框中输入你的任务描述，例如：

1	请帮我总结以下文档的核心观点，生成一份简洁的中文摘要。

4. 上传附件（可选）

如果你的任务涉及文件处理（如 PDF、CSV、图片等），可以点击上传按钮添加附件。

5. 点击 Launch

点击 Launch 按钮，工作流开始执行。你可以在右侧面板实时查看：

每个节点的状态变化（等待中 → 运行中 → 成功/失败）
智能体的实时输出日志
生成的中间结果和最终产物

6. 人机交互

如果工作流中包含 human 类型的节点（如审核节点），执行会暂停并显示输入框。你可以在这里输入审核意见或修改建议，然后提交继续执行。

第五步：编写自定义 YAML 工作流

对于更复杂的需求，你可以编写自己的 YAML 工作流。ChatDev 2.0 的工作流使用 DAG（有向无环图）结构，以下是核心结构说明：

基本工作流结构

version: 0.4.0
vars:
  API_KEY: ${API_KEY}
  BASE_URL: ${BASE_URL}
graph:
  id: my_workflow
  description: 我的第一个工作流
  initial_instruction: |
    你是一个专业的内容创作助手。
  start:
    - 内容创作者
  end:
    - 内容创作者
  nodes:
    - id: 内容创作者
      type: agent
      config:
        provider: openai
        api_key: ${API_KEY}
        base_url: ${BASE_URL}
        name: gpt-4o
        params:
          temperature: 0.1
    - id: 审核员
      type: human
      config:
        description: 请审核上面的内容，输入 ACCEPT 表示通过，否则提供修改意见。
  edges:
    - from: 内容创作者
      to: 审核员
    - from: 审核员
      to: 内容创作者
      condition:
        type: keyword
        config:
          none:
            - ACCEPT
          case_sensitive: false

这个示例工作流包含两个节点：

内容创作者（agent 类型）：调用 LLM 生成内容
审核员（human 类型）：人工审核，只有输入 ACCEPT 才会结束循环

核心节点类型

节点类型	用途
`agent`	调用 LLM 智能体，支持工具、记忆和思考模式
`python`	执行 Python 脚本，共享代码工作区
`human`	暂停等待人工输入
`subgraph`	嵌入子图，复用复杂流程
`passthrough`	上下文过滤，优化图结构
`literal`	输出固定文本
`loop_counter`	限制循环迭代次数
`loop_timer`	限制循环持续时间

第六步：高级功能 — 动态并行执行

ChatDev 2.0 支持动态并行执行，可以自动将任务拆分为多个子任务并行处理。动态配置定义在 边（edge） 级别，而非节点级别：

Map 模式（拆分并行）

将消息拆分为多个单元并行执行，输出扁平化的结果列表：

edges:
  - from: 任务分发器
    to: 研究智能体
    dynamic:
      type: map
      split:
        type: message
      config:
        max_parallel: 5  # 最多 5 个并行

nodes:
  - id: 研究智能体
    type: agent
    config:
      provider: openai
      name: gpt-4o
      prompt_template: "研究以下主题：{{content}}"

Tree 模式（拆分 + 归约）

适合长文本分段摘要等场景，并行处理后递归合并：

edges:
  - from: 文本分割器
    to: 摘要智能体
    dynamic:
      type: tree
      split:
        type: regex
        pattern: "(?s).{1,2000}(?:\\\\s|$)"  # 每约 2000 字符拆分
      config:
        group_size: 3   # 每 3 个结果合并为 1 个
        max_parallel: 10

第七步：使用 Python SDK

ChatDev 还提供了 Python SDK（PyPI 包 chatdev），可以在 Python 代码中直接调用工作流：

1	pip install chatdev

💡 提示：runtime.sdk 是 ChatDev 项目内部路径。在独立项目中使用建议将 ChatDev 仓库作为子模块或通过 PYTHONPATH 设置导入路径。

from runtime.sdk import run_workflow

result = run_workflow(
    yaml_file="yaml_instance/demo.yaml",
    task_prompt="用一句话总结附件文档的核心观点。",
    attachments=["/path/to/document.pdf"],
    variables={"API_KEY": "your-api-key"}
)

if result.final_message:
    print(result.final_message.text_content())

常见问题（FAQ）

Q: ChatDev 2.0 和 1.0 有什么区别？
A: ChatDev 1.0 是”虚拟软件公司”模式，专注于软件开发自动化（CEO、CTO、程序员等角色协作）。2.0（DevAll）已演变为通用的零代码多智能体编排平台，支持数据可视化、3D 生成、深度调研等多样化场景。1.0 代码已移至 chatdev1.0 分支维护。

Q: ChatDev 支持哪些 LLM 模型？
A: ChatDev 使用 OpenAI 兼容接口，支持所有提供 /v1/chat/completions 接口的模型。包括：OpenAI（GPT-4o、o1 等）、Anthropic（Claude）、Google Gemini、本地部署的 Ollama 模型等。

Q: 启动后 Web 页面无法加载？
A: 确认前端 npm run dev 正在运行。检查浏览器控制台是否有错误信息。

Q: 前端无法连接后端？
A: 确认后端 uv run python server_main.py 正在运行。检查端口是否被占用，前后端端口配置是否一致。

Q: 工作流列表为空？
A: 检查 yaml_instance/ 目录是否存在 YAML 文件。可以使用 make sync 命令同步工作流到前端。

Q: 执行过程中 WebSocket 断开？
A: 刷新页面即可重新建立连接。

Q: 想使用本地模型（如 Ollama）？
A: 在 .env 中设置 BASE_URL=http://localhost:11434/v1，API_KEY 可留空或使用任意值。

Q: 如何扩展自定义节点类型？
A: 查看 docs/user_guide/en/workflow_authoring.md 中的节点扩展指南，以及 functions/ 目录下的自定义工具开发示例。

总结

通过本教程，你已经掌握了 ChatDev 2.0 的核心用法：

✅ 从零安装 ChatDev 2.0
✅ 配置 LLM API 密钥
✅ 通过 Web 控制台创建和执行工作流
✅ 编写自定义 YAML 工作流
✅ 使用动态并行执行处理大规模任务
✅ 通过 Python SDK 集成到自己的项目中

ChatDev 2.0 的强大之处在于其零代码的特性——你不需要成为编程专家，也能编排复杂的多智能体协作流程。无论是自动化内容创作、数据分析、还是 3D 生成，ChatDev 都能帮助你轻松实现。

下一步，你可以探索内置的示例工作流（如数据可视化、3D 生成、游戏开发等），或者基于自己的需求创建全新的工作流。

📖 更多文档：ChatDev 官方文档

如何引用本文：本文基于 ChatDev 官方 README（2026-05-22 验证）、workflow_authoring.md、dynamic_execution.md 和 PyPI chatdev 包编写。所有命令和配置均与 ChatDev 2.0 (DevAll) 版本对照验证。