MetaGPT · 多角色 Agent 协作模拟软件公司 · 原理学习与本地运行全指南

项目仓库： https://github.com/geekan/MetaGPT

开源协议：MIT · 主语言：Python（3.9 及以上、低于 3.12） · 运行形态：命令行工具 / Python 库 / 官方 Docker 镜像 · 常驻服务端口：无（CLI 与库调用，产物写入本地 workspace 目录） · 分支：main（命令、配置项以官方仓库最新说明为准）

1 项目简介

MetaGPT 是一个开源的多智能体（Multi-Agent）协作框架：它把一家软件公司里的岗位拆成一个个由大语言模型驱动的角色——产品经理、架构师、项目经理、工程师、QA 等，再用一套精心编排的标准作业流程（SOP）把这些角色串起来。你输入一句话老板需求，框架内部由不同角色依次产出用户故事、竞品分析、需求文档、数据结构、API 设计、任务拆解、代码与测试，最终在本地 workspace 目录生成一个可查看的项目仓库。

框架的核心哲学被作者概括为 Code = SOP(Team)：把人类软件团队沉淀下来的 SOP 具象化为代码，再应用到由 LLM 组成的团队上。项目由 DeepWisdom 团队维护，配套有在线文档、示例仓库、Discord 社区与学术论文（ICLR 2024）。

定位说明：MetaGPT 本身不是一个开箱即用的网页应用，也不内置大模型权重；它是一个编排框架，需要你自备可用的 LLM 接入方式（OpenAI 兼容接口、Azure、Ollama、Groq 等，以官方配置文档支持的 api_type 为准）。本文侧重多 Agent 分工原理、最小可运行示例与本地/容器运行方式，适合作为学习多角色协作编排的入门框架。

1.1 核心信息一览

1.2 适用场景

• 学习多 Agent 系统的基本结构：角色（Role）、动作（Action）、消息、记忆、SOP 流程如何在框架内协作。
• 用一句话需求快速生成一份包含需求文档、设计文档、任务表、代码与测试的项目初稿，作为自己二次开发的起点。
• 研究“软件公司式”分工：产品经理写 PRD、架构师出设计、项目经理拆任务、工程师写代码、QA 写测试并跑测试的流水线如何落地。
• 在自己的 Python 项目里把 MetaGPT 作为库调用，嵌入现有自动化流程；或基于框架二次开发自定义角色、工具与记忆机制。
• 复现官方示例：Data Interpreter 数据分析、多角色辩论、研究员、票据助手等用例（见官方文档 Use Cases 章节）。

1.3 能力边界（官方口径）

• MetaGPT 输入一句话需求后输出的是项目初稿与文档集合，不保证代码可直接编译上线；生成内容需要开发者自行审查、调试与补全。
• 框架本身不提供大模型，也不附带模型 API Key；所有推理都通过你在配置文件中指定的模型接口完成，效果与成本取决于所选模型。
• 内置角色与 SOP 会随版本演进；官方文档明确标注部分示意图为“逐步实现中”，具体角色行为以当前版本代码与文档为准。
• 框架提供可选的 RAG、经验池、长期记忆、浏览器工具、搜索工具等扩展能力，需要对应依赖与外部服务配置；未配置时相关功能不启用。
• 项目面向研究、实验与开发学习；生产环境中的权限控制、审计、合规要求需要使用者自行补充。

2 功能特性

2.1 角色化分工与 SOP 流水线

• 内置 ProductManager（产品经理）、Architect（架构师）、ProjectManager（项目经理）、Engineer（工程师）、QA 等角色，各自承担官方 SOP 中对应的动作：写 PRD、写设计、拆任务、写代码、写测试、跑测试。
• 角色之间通过消息传递上下文，上游角色的产物（文档、数据结构、API 列表）作为下游角色的输入，形成有顺序的协作链路。
• 配置文件支持为不同角色单独指定不同的模型接入（见第 8 章 roles 配置段）。

2.2 一句话需求到项目仓库

• 命令行执行 metagpt "Create a 2048 game" 后，框架在 ./workspace 下生成包含文档与代码的项目目录。
• 库模式 generate_repo("Create a 2048 game") 返回 ProjectRepo 对象，可在 Python 代码中直接读取仓库结构与文件。

2.3 Data Interpreter 数据分析角色

• 提供 metagpt.roles.di.data_interpreter.DataInterpreter 角色，可执行数据分析、绘图等任务，是框架内置的面向数据场景的 Agent 封装。

2.4 多模型接入与可替换组件

• llm.api_type 支持 OpenAI、Azure、Ollama、Groq 等类型（完整取值见官方 LLMType 定义与配置文档）；可配置 base_url、proxy、timeout、pricing_plan。
• 浏览器工具支持 Playwright 与 Selenium；内置 Mermaid 图表渲染配置；可接入 Google 搜索、Redis、S3、经验池（Chroma/BM25）等组件。

2.5 可扩展的角色与记忆体系

• 支持自定义角色、动作、工具；配置项包含经验池 exp_pool（长期/短期经验检索、BM25 或 Chroma 向量存储、LLM 重排）与角色长期记忆 role_zero。
• 支持 RAG 扩展安装（源码方式安装 .[rag] 附加依赖）。

2.6 配套示例与学术资料

• 官方文档提供 Agent 101、MultiAgent 101 教程，以及辩论、研究员、票据助手等用例；论文 MetaGPT: Meta Programming for A Multi-Agent Collaborative Framework 已被 ICLR 2024 收录。

3 官方界面预览

MetaGPT 没有图形化控制台，其核心可视化素材是官方 README 中的“软件公司多角色示意图”：SoftwareCompany 作为总控节点，连接 Boss、ProductManager、Architect、ProjectManager、Engineer、QA 等角色与各自动作。

上图展示的是框架的目标角色结构：Boss 提出需求，ProductManager 写/修订 PRD，Architect 写/修订设计并评审 PRD 与代码，ProjectManager 拆任务、派任务并评审设计，Engineer 写代码、评审代码、调试代码，QA 写测试并运行测试。实际运行时的角色清单与动作实现以当前版本官方代码为准。

4 官方跳转链接汇总

下表列出项目相关的官方入口，均可直接点击访问。

5 前置要求与服务器配置

5.1 软件前提

• Python 3.9 或更高版本、且低于 3.12：官方 README 明确要求该版本区间；可用 python --version 检查。版本不符时建议使用 conda 单独建环境：conda create -n metagpt python=3.9 && conda activate metagpt。
• Node.js 与 pnpm：官方 README 要求在实际使用前安装 Node.js 与 pnpm。
• 可用的 LLM 模型接入：需要一组模型接口凭据（OpenAI 兼容接口、Azure、Ollama、Groq 等，以官方配置文档为准），并能在运行环境中访问对应接口。
• Docker（仅容器方式需要）：官方镜像方式需要本机已安装 Docker Engine。
• 稳定网络：模型推理、可选浏览器工具与搜索工具均需要网络访问。

5.2 硬件与系统建议（官方口径）

5.3 端口与目录分配

提示：MetaGPT 不开放 Web 控制台端口，因此不存在“登录后台”的环节；远程服务器上运行时，只需要保证本机到模型接口的网络通畅即可。

6 方式一：Docker 镜像运行（官方镜像，适合服务器与隔离环境）

官方文档提供了 metagpt/metagpt:latest 镜像的运行方式。容器内已装好框架依赖，适合在隔离环境中运行 CLI 命令，避免污染本机 Python 环境。

6.1 准备配置文件

# 1. 拉取官方镜像
docker pull metagpt/metagpt:latest

# 2. 在宿主机创建配置与产物目录（Windows 下请换成 Docker 有权限的目录）
mkdir -p /opt/metagpt/{config,workspace}

# 3. 从镜像中导出默认配置模板到宿主机
docker run --rm metagpt/metagpt:latest cat /app/metagpt/config/config2.yaml \
  > /opt/metagpt/config/config2.yaml

# 4. 编辑配置，填入模型接入信息（字段说明见第 8 章）
vim /opt/metagpt/config/config2.yaml

6.2 一次性运行任务

docker run --rm \
    --privileged \
    -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
    -v /opt/metagpt/workspace:/app/metagpt/workspace \
    metagpt/metagpt:latest \
    metagpt "Write a cli snake game"

官方文档说明：使用 --privileged 是为了让容器内浏览器工具具备所需权限；配置文件与 workspace 目录通过卷挂载到宿主机持久保存。

6.3 常驻容器后进入终端执行命令

# 后台启动一个常驻容器
docker run --name metagpt -d \
    --privileged \
    -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
    -v /opt/metagpt/workspace:/app/metagpt/workspace \
    metagpt/metagpt:latest

# 进入容器终端
docker exec -it metagpt /bin/bash

# 在容器内执行命令行任务
$ metagpt "Write a cli snake game"

6.4 自行构建镜像（可选）

git clone https://github.com/geekan/MetaGPT.git
cd MetaGPT && docker build -t metagpt:custom .

7 方式二：pip 安装与源码本地运行

7.1 创建隔离 Python 环境

# 方式 A：conda（推荐，便于锁定 Python 3.9–3.11 区间）
conda create -n metagpt python=3.9 && conda activate metagpt

# 方式 B：venv（Python 版本需自行确认在 3.9 以上、3.12 以下）
python3 -m venv .venv && source .venv/bin/activate

7.2 安装稳定版 CLI

pip install --upgrade metagpt

也可以直接从 GitHub 主干安装：

pip install --upgrade git+https://github.com/geekan/MetaGPT.git

7.3 生成并填写配置

# 生成默认配置文件 ~/.metagpt/config2.yaml
metagpt --init-config

编辑 ~/.metagpt/config2.yaml，最小可用配置示例（以 OpenAI 兼容接口为例，api_type 取值以官方文档为准）：

llm:
  api_type: "openai"
  model: "gpt-4-turbo"
  base_url: "https://api.openai.com/v1"
  api_key: "YOUR_API_KEY"

7.4 命令行运行第一个任务

metagpt "Create a 2048 game"
# 任务完成后，项目仓库位于 ./workspace 目录

7.5 作为 Python 库调用最小示例

from metagpt.software_company import generate_repo
from metagpt.utils.project_repo import ProjectRepo

repo: ProjectRepo = generate_repo("Create a 2048 game")  # 也可 ProjectRepo("<路径>")
print(repo)  # 打印仓库结构与文件

7.6 Data Interpreter 数据分析最小示例

import asyncio
from metagpt.roles.di.data_interpreter import DataInterpreter

async def main():
    di = DataInterpreter()
    await di.run("Run data analysis on sklearn Iris dataset, include a plot")

asyncio.run(main())  # 在 Jupyter Notebook 中可直接 await main()

7.7 源码克隆与开发模式

git clone https://github.com/geekan/MetaGPT.git
cd MetaGPT

# 基础安装
pip install --upgrade -e .

# 需要 RAG 能力时安装附加依赖
pip install -e .[rag]

开发调试、运行测试与代码规范的具体命令以仓库 CONTRIBUTING.md 与官方开发文档为准。

8 配置项说明

配置文件默认为 ~/.metagpt/config2.yaml，字段可对照仓库 config/config2.example.yaml。下表按官方示例逐项说明用途；标注“可选”的字段不填时使用默认行为。

8.1 主模型 llm

8.2 嵌入模型 embedding

8.3 角色级模型覆盖 roles

可按角色单独指定模型接入，示例中包含 ProductManager、Architect、ProjectManager、Engineer；每个角色块下的字段与 llm 段一致（api_type、base_url、api_key、proxy、model、api_version 等）。不单独配置的角色回退使用主 llm 配置。

8.4 输出修复与全局代理

8.5 搜索、浏览器与图表

8.6 外部存储与经验记忆

8.7 其他可选服务配置

提示：以上字段名与取值来自官方 config2.example.yaml；新增版本可能调整字段，部署前请对照官方配置文档与示例文件核对。

9 常用运维命令

9.1 环境与包管理

# 查看当前 Python 版本（确认在 3.9 以上、3.12 以下）
python --version

# 升级 MetaGPT 稳定版
pip install --upgrade metagpt

# conda 环境激活 / 退出
conda activate metagpt
conda deactivate

9.2 配置与任务执行

# 重新生成 / 查看默认配置
metagpt --init-config

# 命令行执行一次需求
metagpt "Create a 2048 game"

# 查看当前目录下的产物
ls -R ./workspace

9.3 Docker 方式运维

# 查看容器日志
docker logs -f metagpt

# 停止并删除常驻容器
docker stop metagpt && docker rm metagpt

# 拉取最新镜像后重建容器
docker pull metagpt/metagpt:latest

# 查看本地镜像与卷占用
docker images | grep metagpt
docker volume ls

9.4 产物与配置备份

• 备份 ~/.metagpt/config2.yaml（本机 pip 方式）或 /opt/metagpt/config/config2.yaml（Docker 方式）。
• 备份 workspace 目录即可保留历次生成的文档与代码；配置文件中的模型密钥属于敏感信息，不要随产物仓库公开提交。

10 常见故障排查

10.1 安装阶段 Python 版本报错

现象：pip install metagpt 后导入报语法错误或依赖解析失败。 排查：执行 python --version，确认版本在 3.9 及以上、且低于 3.12；版本不符时用 conda create -n metagpt python=3.9 重建环境后重试。

10.2 提示缺少 Node.js / pnpm

现象：实际运行到需要前端或图表渲染的环节时报缺少命令。 排查：先按官方 README 安装 Node.js 与 pnpm，确认 `node -v`、pnpm -v 可正常输出版本号后重启任务。

10.3 模型接口 401 / 403 / 认证失败

现象：任务启动后角色调用模型返回认证错误。 排查：检查 config2.yaml 中 llm.api_key 是否填写、base_url 是否指向正确兼容地址；确认密钥在模型服务侧未过期、未欠费；走代理网络时核对 llm.proxy 与全局 proxy 配置。

10.4 模型接口超时或连接失败

现象：角色长时间无响应后超时。 排查：先在本机用 curl 验证 base_url 连通性；必要时调大 llm.timeout；网络受限环境配置 proxy；确认所选模型名称在服务商处确实可用。

10.5 模型输出不是合法 JSON

现象：日志中出现输出解析失败、重试修复提示。 排查：保持 repair_llm_output: true；更换指令更明确的任务描述；必要时在 roles 段为该角色指定更稳定的模型；此类错误通常与模型遵循指令能力相关。

10.6 RAG / 经验池 / 长期记忆功能不生效

现象：启用经验池或记忆后检索为空或报错。 排查：源码安装时确认执行了 pip install -e .[rag]；exp_pool.retrieval_type: chroma 需要正确配置 embedding；role_zero.enable_longterm_memory 默认 false，需要显式开启并检查持久化目录写权限。

10.7 浏览器 / Mermaid 图表工具报错

现象：需要打开网页或生成流程图的动作失败。 排查：核对 browser.engine 与 browser.browser_type 是否匹配已安装的浏览器内核；Playwright 浏览器按需执行官方文档对应的安装命令；mermaid.pyppeteer_path 在 macOS 上需指向本机 Chrome 等可执行文件路径。

10.8 产物目录权限不足或中文路径异常

现象：写 workspace 时 Permission denied，或部分工具在中文/空格路径下异常。 排查：确认当前用户对工作目录有写权限；Docker 方式检查挂载目录属主；尽量使用英文路径运行任务。

11 风险与合规说明

• 许可证：MetaGPT 代码以 MIT 许可证发布，允许自由使用、修改与再分发，商用亦在授权范围内；使用时请保留原版权与许可证声明。引用论文请按官方 README 提供的 BibTeX 格式著录。
• 生成内容审查：框架产出的文档与代码属于 AI 辅助生成的初稿，可能包含错误、漏洞、过时 API 或未授权引用；用于正式项目前必须由开发者审查、测试与重构，作者与框架不保证产出可直接用于生产环境。
• 模型服务条款与数据隐私：任务上下文、代码片段、文件内容会发送到你配置的模型服务商；使用第三方商业模型须遵守对应服务条款与数据处理约定；涉及商业机密或未公开代码时，优先使用自建或私有部署模型服务并核对合规要求。
• 敏感信息保管：config2.yaml 中的 api_key、代理、Redis/S3、语音服务密钥等均为敏感凭据，不要提交到公开仓库，不要写入文章、截图或共享配置；轮换密钥时直接编辑配置文件即可。
• 工具安全：浏览器、搜索、代码执行等工具能力以框架实际安装的扩展为准；只加载自己信任的工具与 MCP/外部服务，避免在不受控环境中执行未审核的自动化操作。
• 非框架本身风险：MetaGPT 是开源研究与开发框架，不附带任何商业模型承诺、SLA 或产品保证；官方衍生商业产品 MGX 与本框架本体相互独立，选择时请注意区分。