AgentGPT 快速上手指南：在浏览器里配置并部署自主 AI 代理

AgentGPT 是一个可以在浏览器里组装、配置并部署自主 AI 代理的工具。你给它起一个名字，再写下一个目标，它就会围绕这个目标自行拆解任务、逐条执行，并根据执行结果调整后续动作，直到目标达成或流程结束。它适合想快速验证「让 AI 自己推进一件事」这类想法的人：不需要先搭一套复杂的编排框架，也不必从零写调度逻辑，把目标描述清楚就能看到代理的思考与执行过程。如果你更习惯用现成的在线工具页面对照操作，可以先打开 AgentGPT 了解入口，再回到本文按步骤完成本地部署。

需要先说明一点：AgentGPT 的完整能力依赖后端服务、数据库和若干第三方 API 密钥，因此「在浏览器里用」并不等于「什么都不用装」。下面按准备工作、操作步骤、完整示例、注意事项四部分展开，把每一步的命令和参数写清楚。

准备工作

在动手之前，先把依赖项备齐。缺任何一项，安装脚本都会在中途停下来，或者服务起来之后代理无法真正执行任务。

必备的软件环境

• 代码编辑器：例如 Visual Studio Code。它同时提供集成终端，后续命令都在这里执行。
• Node.js：前端基于 Next.js，需要 Node.js 运行时。安装版本请以项目仓库当前的说明为准。
• Git：用于克隆仓库。
• Docker：安装完成后需要创建账户、打开 Docker 应用并保持登录状态。数据库等依赖服务通过容器启动。

必备的 API 密钥

• OpenAI API 密钥：必填。代理的思考与任务生成依赖大模型能力，没有这个密钥代理无法运转。
• Serper API 密钥：可选。用于联网搜索能力，代理需要查资料时才会用到。
• Replicate API 令牌：可选。用于接入 Replicate 上的模型能力。

两个可选密钥不填也能完成安装，只是代理在需要搜索或调用外部模型时会受限。建议第一次部署时先只填必填项，把流程跑通，再按需补充。

数据库

AgentGPT 使用 MySQL 作为数据库。安装脚本会引导你完成数据库相关配置，因此不需要提前手工建库建表，但要保证 Docker 处于运行状态，否则容器起不来。

操作步骤

第一步：打开编辑器与终端

启动代码编辑器，打开一个用于存放项目的目录。然后在编辑器内打开集成终端：Windows 上使用 Ctrl + ~，macOS 上使用 Control + ~。后续所有命令都在这个终端里执行。

第二步：克隆仓库并进入目录

在终端中执行克隆命令，然后切换到项目目录：

git clone <仓库地址>
cd AgentGPT

仓库地址请以项目当前发布页给出的为准。克隆完成后，当前路径应当位于 AgentGPT 目录下，可以用 ls（macOS/Linux）或 dir（Windows）确认能看到安装脚本。

第三步：运行安装脚本

AgentGPT 提供了一个自动化的 CLI 安装程序，它会依次帮你配置环境变量（含 API 密钥）、数据库（MySQL）、后端（FastAPI）和前端（Next.js）。按操作系统选择对应脚本。

macOS 与 Linux：

./setup.sh

Windows：

./setup.bat

如果脚本没有执行权限，在 macOS/Linux 上先补上权限再运行：

chmod +x setup.sh
./setup.sh

第四步：按脚本指引填写配置

脚本运行后会以交互方式逐项询问配置。需要准备和填写的内容大致分为四类：

1. 环境变量与 API 密钥：粘贴 OpenAI API 密钥；如果准备了 Serper 与 Replicate 的密钥，在这一步一并填入，没有就留空或跳过。
2. 数据库配置：脚本会引导完成 MySQL 相关设置。保持 Docker 已登录并运行，让容器正常拉起。
3. 后端服务：基于 FastAPI 的后端会被配置并启动。
4. 前端服务：基于 Next.js 的前端会被配置并启动。

整个过程按提示回车确认即可，遇到不确定的选项不要随意改动默认值，先让脚本按推荐配置走完。

第五步：确认服务全部启动并访问

脚本执行结束后，确认所有服务都处于运行状态，然后在浏览器中访问本地地址进入界面。首次进入通常需要注册或登录账号，登录后即可创建代理。

第六步：创建并运行第一个代理

进入界面后，创建代理只需要两项输入：

• 代理名称：自定义，用于区分不同代理。
• 目标：用一句或几句自然语言描述你希望它达成的事情。

提交后，代理会开始围绕目标思考任务、执行任务，并从结果中学习，逐步推进。界面上可以看到它的思考与执行记录，据此判断目标描述是否足够明确。

一个完整示例

下面从零走一遍最小可运行流程，假设使用 macOS 或 Linux，Windows 用户把脚本名换成 setup.bat 即可。

1. 确认前置条件

• 已安装 Node.js、Git、Docker，且 Docker 应用已打开并登录。
• 已拿到 OpenAI API 密钥；Serper 与 Replicate 密钥暂不准备。

2. 打开终端并克隆项目

git clone <仓库地址>
cd AgentGPT

3. 赋予脚本执行权限并运行

chmod +x setup.sh
./setup.sh

4. 按提示填写

在询问 OpenAI API 密钥时粘贴密钥；询问 Serper、Replicate 时直接跳过；数据库环节保持 Docker 运行，让脚本完成 MySQL 配置；后端与前端按默认配置启动。

5. 访问界面

脚本提示全部服务就绪后，在浏览器打开本地地址，完成账号登录。

6. 创建代理

名称填一个便于识别的名字，目标写成一个具体、可验证的句子，例如「整理某个主题的要点并输出一份结构化清单」。提交后观察代理的思考与执行记录，如果它反复在同一个子任务上打转，说明目标描述过于宽泛，回到创建页把目标改得更具体再试。

这个示例覆盖了从环境准备到代理跑起来的最小闭环。跑通之后再回头补 Serper 密钥以启用搜索能力，或补 Replicate 令牌接入更多模型，都是增量改动，不影响已有配置。

注意事项

Docker 必须处于登录状态

安装脚本依赖容器启动数据库等服务。Docker 未安装、未打开或未登录，都会导致安装中途失败。遇到服务起不来的情况，先检查 Docker 状态，再重新执行脚本。

可选密钥缺失会限制能力

Serper 与 Replicate 的密钥是可选项，不填不影响安装完成，但代理在需要联网搜索或调用对应模型时会无法执行相关任务。如果代理的表现明显受限于信息获取，优先检查这两项是否配置。

目标描述决定代理表现

代理是围绕你给出的目标自行拆解任务的，目标越模糊，它越容易在无关方向上消耗步骤。把目标写成可判断是否完成的形式，比堆砌形容词更有效。

密钥与费用

OpenAI、Serper、Replicate 均为第三方服务，各自有独立的计费方式与配额限制。代理自主执行任务会持续产生调用，运行前应了解所用服务的计费规则。具体价格、配额与可用模型请以各服务官网当前信息为准。

版本与依赖以仓库说明为准

项目依赖的 Node.js 版本、脚本行为、环境变量名称可能随版本变化。安装前先查看项目当前发布页的说明，不要照搬旧版本的步骤。本文涉及的功能范围与部署方式同样应以官网当前信息为准。

技术栈概览

了解底层组成有助于排查问题。AgentGPT 的基础框架为 create-t3-app 与 FastAPI-template；前端使用 Next.js 13、TypeScript 与 FastAPI；身份验证使用 Next-Auth.js；ORM 为 Prisma 与 SQLModel；数据库为 Planetscale；样式使用 TailwindCSS 与 HeadlessUI；模式验证使用 Zod 与 Pydantic；LLM 工具为 Langchain。当某个环节报错时，可以据此判断问题出在前端、后端、数据库还是模型调用层。