MetaGPT

MetaGPT 快速入门

把一个产品经理、一个架构师、几个工程师塞进同一个 Python 进程,让它替你开一家「AI 软件公司」。

这是什么?适合谁?

MetaGPT 是由 DeepWisdom 团队(在 GitHub 上的组织名为 FoundationAgents)开源的多 Agent 框架,核心创新点在于把软件公司的标准作业流程(SOP)编码进了 Agent 协作。在 MetaGPT 里,你不需要自己编排 Agent 的发言顺序,只要给它一句话需求,框架就会自动按「产品经理 → 架构师 → 项目经理 → 工程师 → QA」这样一条传统软件公司的标准流水线往下走。

具体来说,当你输入「做一个 2048 小游戏」,MetaGPT 内部会触发:

• 产品经理 Agent 先写出一份 PRD.md(产品需求文档),包含用户故事、需求列表、验收标准;
• 架构师 Agent 接着输出一份系统设计,确定技术栈、模块划分、接口定义;
• 项目经理 Agent 把需求拆成可执行的任务,排到 tasks.json 里;
• 工程师 Agent 真正写代码,产出 2048.py、game.py 之类的文件;
• QA Agent 跑测试,反馈 bug。

最终,你会看到一份完整的项目目录,结构跟人类开发的差不多——docs/prd/、docs/system_design/、workspace/ 这种层级。MetaGPT 在 2024 年发布后因为这种「一气呵成」的开发体验迅速走红,GitHub 上累计获得大量 stars。

适合谁?如果你是独立开发者或小团队,想用 LLM 一次性把「从需求到代码」全跑一遍体验效果,MetaGPT 提供了非常完整的 demo;如果你是研究多 Agent 协作范式的人,MetaGPT 是 SOP-driven 这种设计思路的代表案例,值得读源码;如果你是产品经理或运营,想让 AI 帮你快速搭一个 demo 出来看效果,MetaGPT 表现稳定。

不适合「我有一个很具体的 bug 需要修」——那种场景直接用 Cursor 或 Claude Code 更合适;也不适合需要持续迭代的长期项目——MetaGPT 一次性跑完整套流程的代价较高,长期迭代建议把它的输出作为起点,再人工维护。

准备工作

开始之前,请准备以下几样:

1. Python 3.9 及以上版本:MetaGPT 对较新的 Python 特性有依赖,推荐 3.10+。访问 https://www.python.org/downloads/ 安装。
2. 大模型 API Key:MetaGPT 默认调用 OpenAI 的 gpt-4o 或 gpt-4-turbo(因为它要写很长的 PRD 和代码,弱模型效果会差很多);你也可以配 Azure、DeepSeek、Anthropic 等。
3. Git:用于克隆仓库。访问 https://git-scm.com/ 安装。
4. Node.js 18+(可选):某些示例会用到前端项目生成,按需安装。

3 步快速上手

第 1 步:克隆并安装 MetaGPT

打开终端,执行:

git clone https://github.com/FoundationAgents/MetaGPT.git
cd MetaGPT
pip install -e .

pip install -e . 会以「可编辑」模式安装,这样后续拉了新代码不用重装。安装过程可能会拉一些数据科学相关的依赖(numpy、pandas 之类),耐心等几分钟。

接着初始化一下配置:

metagpt --init-config

这条命令会在 ~/.metagpt/config2.yaml 生成一个默认配置,你可以编辑它填入自己的 API key。

第 2 步:配置 API Key

用编辑器打开 ~/.metagpt/config2.yaml,把里面 llm.api_key 改成你自己的 key,顺便把 llm.model 改成你要用的模型(默认是 gpt-4-turbo)。一个最小化的配置示例:

llm:
  api_type: "openai"
  api_key: "sk-..."
  model: "gpt-4o-mini"
  base_url: "https://api.openai.com/v1"

如果你想用 DeepSeek,把 api_type 改成 "deepseek",base_url 改成 DeepSeek 的端点即可。

第 3 步:跑一个最小项目

在终端里执行:

metagpt --idea "写一个命令行贪吃蛇游戏,要求支持计分、暂停、彩色输出"

MetaGPT 会开始按 SOP 一步步跑,你会在终端看到每个角色 Agent 的思考日志。等几分钟后,在 workspace/ 目录里会看到完整的项目结构,包括 docs/ 下的需求文档和 snake_game/ 下的可执行 Python 代码。

直接 cd workspace/snake_game && python main.py 就能玩你刚做出来的贪吃蛇了。

常见踩坑

1. 「装到一半失败」:MetaGPT 依赖较多,如果你机器上 Python 环境比较乱,建议用 conda 单独建一个 3.10 的环境,再在那个环境里 pip install。
2. 「跑到一半 OOM 或 token 超限」:MetaGPT 一次性会生成很多长文档(尤其架构师阶段),弱模型上下文不够会直接报错;建议用 gpt-4o 或 gpt-4-turbo,或者在配置里调小 llm.max_token。
3. 「生成的项目代码跑不起来」:MetaGPT 的「一次性」模式下,工程师 Agent 没机会跟 QA Agent 多轮迭代,生成的代码可能有语法/依赖错误;实际使用中需要人工把项目跑起来,再修一轮。
4. 「想用 Claude 模型但报错」:在 config2.yaml 里配置 Anthropic 的 api_type 后,有些方法名 OpenAI 不一样,需要同步改 metagpt/provider/ 下的对应文件,或者用 OpenAI 兼容代理。
5. 「想让它做非软件开发的事」:MetaGPT 的 SOP 是「软件公司」专用,直接拿去做内容生成、研究会非常别扭;可以参考它的设计思路,但任务本身最好用 CrewAI 之类的通用框架。
6. 「生成文件位置找不到」:默认输出在当前目录的 workspace/ 下,可以用 --output-path 自定义路径,避免多项目相互覆盖。

初级用法

• 生成一个完整 Demo:给一句「做一个命令行 todo 应用,支持增删改查」,等 5 分钟就能拿到带需求文档和源码的完整项目。
• 学习它的 SOP 输出:workspace/docs/ 下的 prd.md、system_design.md 本身就是很好的产品/架构学习材料,即使不用它的代码也能读。
• 指定技术栈:在 idea 里加上「用 FastAPI + SQLite」,架构师 Agent 会按你的要求选型,产出的代码直接可用度更高。

高级玩法

• 自定义 Role 列表:你可以继承 Role 类,新增自己的角色,比如「DevOps 工程师」自动写 Dockerfile 和 CI 脚本;通过 Team 注册并把它们串进 SOP。
• 动作(Action)扩展:每个角色能做什么事,本质是一组 Action 类。你可以实现自己的 Action(比如「调用内部 CRM API」),让特定角色具备调用业务系统的能力。
• 多轮增量开发:第一轮用 MetaGPT 跑出骨架后,把生成的项目作为新起点,人工改完再让 MetaGPT 跑「第二轮需求」,模拟真实团队迭代。

小技巧

1. 写清楚需求里的「非功能性指标」:「响应时间 < 200ms」「支持 1000 并发」这类条件写进 idea,架构师 Agent 会把它们落到设计里。
2. 先用 gpt-4o-mini 跑通再换强模型:小项目用 gpt-4o-mini 性价比更好,只在效果明显差时再切 gpt-4o。
3. 保留每次的 workspace:MetaGPT 默认会覆盖 workspace,加 --output-path ./runs/2026-06-17-snake/ 这种命名可以按时间归档,方便对比。
4. 读源码理解设计:metagpt/team.py 和 metagpt/roles/ 下的代码是学习「SOP-driven 多 Agent」的最佳资料,推荐作为进阶阅读。
5. 别指望一次跑完美:把 MetaGPT 当「高级代码生成器」,把它给的代码当作 v0.1,再由你或 Claude Code/Cursor 接手修。

参考链接

• MetaGPT GitHub 仓库
• MetaGPT 官方主页
• MetaGPT 论文:MetaGPT: Meta Programming for A Multi-Agent Collaborative Framework
• MetaGPT 示例项目集
• DeepWisdom 团队博客