GPT Engineer：自然语言规格一键生成代码｜CLI 安装与使用全指南

仓库：https://github.com/gpt-engineer-org/gpt-engineer 官方文档：https://gpt-engineer.readthedocs.io/ 许可证：MIT（见仓库 LICENSE）运行形态：命令行工具（无 Web 端口），Python 3.10 – 3.12

1. 项目简介

gpt-engineer 是最早的"用自然语言描述软件、让 AI 写代码并执行"的开源实验性平台。用户在项目目录里放一个名为 prompt（无扩展名）的文件，CLI 会根据它生成完整代码、迭代改进，还能跑 benchmark。

1.1 核心信息一览

项目	内容
仓库	gpt-engineer-org/gpt-engineer
定位	自然语言规格 → 代码的实验性 CLI
许可证	MIT
运行形态	命令行（`gpte`），无守护进程、无默认端口
Python 版本	官方支持 3.10 – 3.12；3.8/3.9 最后版本为 0.2.6
安装方式	`pip install gpt-engineer` 或 poetry 源码
模型	OpenAI / Azure OpenAI / Anthropic，可接本地开源模型

1.2 适用场景

想快速从一句话规格生成一个小型脚手架 / 原型；
想在已有代码库上让 AI 继续迭代改进（-i 模式）；
想给自己的 agent 跑 APPS / MBPP 公开 benchmark。

1.3 能力边界（官方口径）

官方 README 明确建议：想要"有观点、托管化的服务"去看 gptengineer.app；想要"维护良好的可 hack CLI"去看 aider；
本仓库是实验性平台，社区使命是"维护 coding agent builder 可用的工具、促进开源协作"；
默认模型是 OpenAI，本地模型需额外配置（见 open_models 文档）。

2. 功能特性

自然语言规格驱动：写 prompt 文件，AI 生成并执行代码；
改进模式：gpte <dir> -i 让 AI 在已有代码上继续迭代；
Pre-prompts 定制：用自己的 preprompts/ 覆盖 agent 身份，通过 --use-custom-preprompts 启用，让 agent 跨项目记忆；
Vision 输入：--image_directory 配合 vision 模型，把 UX 图、架构图作为上下文；
多模型后端：OpenAI、Azure、Anthropic，以及通过文档配置的本地开源模型（如 WizardCoder）；
bench 命令：内置 bench 二进制，跑 APPS / MBPP 等公开数据集评估自定义 agent。

3. 官方界面预览

官方 README 未提供横幅截图，仅含 badges 与一段 demo 视频（GitHub assets 链接）。启动后在终端运行，无 Web 界面。

4. 官方跳转链接汇总

仓库主页：https://github.com/gpt-engineer-org/gpt-engineer
官方文档（Read the Docs）：https://gpt-engineer.readthedocs.io/
自定义 / 本地模型配置：https://gpt-engineer.readthedocs.io/en/latest/open_models.html
Windows 说明：https://github.com/gpt-engineer-org/gpt-engineer/blob/main/WINDOWS_README.md
Docker 说明：https://github.com/gpt-engineer-org/gpt-engineer/tree/main/docker
Codespaces：https://github.com/codespaces/badge
Discord：https://discord.gg/8tcDQ89Ej2
商业版 gptengineer.app：https://gptengineer.app/

5. 前置要求与服务器配置

Python 3.10 – 3.12（官方支持区间）；
一个 OpenAI API Key（或 Anthropic / Azure 凭据）；
可选：Serper、Replicate 等第三方 Key（README 未强制）；
无 GPU 要求，无端口占用，无数据库。

6. 方式一：pip 安装（推荐）

# 稳定版
python -m pip install gpt-engineer

配置 API Key，三选一：

# 方式 A：环境变量
export OPENAI_API_KEY=[your api key]

# 方式 B：.env 文件
cp .env.template .env
# 然后编辑 .env 填入 OPENAI_API_KEY

创建新项目并生成代码：

# 1. 建一个空目录
mkdir my-new-project && cd my-new-project
# 2. 在目录里写一个名为 prompt 的文件（无扩展名），描述你要做什么
# 3. 回到 gpt-engineer 目录运行
gpte projects/my-new-project

在已有代码上迭代改进：

gpte projects/my-old-project -i

7. 方式二：源码 / 本地开发运行

git clone https://github.com/gpt-engineer-org/gpt-engineer.git
cd gpt-engineer
poetry install
poetry shell

然后同样运行 gpte <project_dir>。Vision 模式示例：

gpte projects/example-vision gpt-4-vision-preview \
  --prompt_file prompt/text \
  --image_directory prompt/images -i

也可以用 Docker（见 docker/README.md）或在浏览器里通过 GitHub Codespaces 运行。

8. 配置项说明

配置	说明
`OPENAI_API_KEY`	必需，OpenAI API Key；可用环境变量或 `.env`
`.env.template`	复制为 `.env` 后填写
`preprompts/`	自定义 agent 身份，配合 `--use-custom-preprompts`
`--image_directory`	Vision 模型时传入图片目录
`-i`	改进已有代码，而非从零生成
模型名（第二个 CLI 参数）	例如 `gpt-4-vision-preview`，可换成 Anthropic / 本地模型

9. 常用运维命令

# 查看版本
gpte --help

# 生成新项目
gpte projects/my-new-project

# 改进已有项目
gpte projects/my-old-project -i

# 升级
pip install -U gpt-engineer

# 卸载
pip uninstall gpt-engineer

# 跑 benchmark（安装后自带 bench 二进制）
bench --help

10. 常见故障排查

Python 版本不兼容：官方支持 3.10–3.12，3.8/3.9 请用 gpt-engineer==0.2.6；
OPENAI_API_KEY 未设置：报 401 或认证失败，检查环境变量 / .env；
prompt 文件找不到：文件名必须是 prompt（无扩展名），放在项目目录根；
想接本地模型：参考官方 open_models 文档，配置对应 base_url 与模型名；
Windows 路径问题：看仓库 WINDOWS_README.md。

11. 风险与合规说明

MIT 许可，可自由使用与二次开发；
生成的代码版权归你所有，但 AI 生成代码可能存在许可证 / 版权风险，商用前请自行审查；
默认走 OpenAI / Anthropic 等付费 API，费用由你的账号承担；
本文为社区部署笔记，命令以官方 README 与 readthedocs 最新版本为准。