AgentGPT 本地部署实战：用内置 CLI 一键装配并运行浏览器内的自主 AI Agent

AgentGPT 本地部署实战用内置 CLI 一键装配并运行浏览器内的自主 AI Agent【免费下载链接】AgentGPT Assemble, configure, and deploy autonomous AI Agents in your browser.项目地址: https://gitcode.com/gh_mirrors/ag/AgentGPTAgentGPT 是一个开源的自主 AI Agent 平台允许你在浏览器中装配、配置并部署自己的 AI Agent为它命名、设定任意目标它会自主拆解任务、逐步执行并从结果中学习。本文以仓库根目录 README.md 为主线结合 setup.sh、docker-compose.yml、.env.example 与 cli 目录下的源码实现完整还原从环境准备、API Key 配置到前端/后端/数据库三服务联动的本地部署全流程并逐项解释 CLI 生成的每个环境变量的作用。读完本文你将能够独立在本机一键拉起整套 AgentGPT 服务并理解其背后「CLI 生成配置 → Docker Compose 编排 → Next.js FastAPI MySQL 三服务协作」的部署原理。AgentGPT 是什么浏览器里的自主 AI Agent按 README.md 的定位AgentGPT 允许你「配置并部署自主 AI Agent」命名一个自定义 AI让它去完成你能想到的任何目标。它的工作模式是——Agent 会自主思考需要执行的任务thinking of tasks、执行任务executing them、并根据结果学习learning from the results形成「目标 → 任务 → 执行 → 反馈 → 再规划」的循环。这一模式在仓库源码中也有清晰的对应实现前端侧的任务编排与执行状态机位于 next/src/services/agent/如 autonomous-agent.ts 与agent-work/下的create-task-work.ts、execute-task-work.ts、start-task-work.ts等工作流文件后端侧对应的是 FastAPI 平台中的 Agent 服务与工具集见 platform/reworkd_platform/web/api/agent/analysis.py、prompts.py、tools/目录等。部署者无需深入这些实现即可运行整套系统但了解这条链路有助于在排障时定位问题。技术栈一览README 的 Tech Stack 一节完整列出了 AgentGPT 的选型这些组件在仓库各子目录中均可找到对应实现类别技术仓库中的对应位置脚手架create-t3-app FastAPI-templatenext/Next.js 前端、platform/FastAPI 后端框架Next.js 13 TypeScript前端、FastAPI后端next/package.json、platform/pyproject.toml认证Next-Auth.jsnext/src/pages/api/auth/[...nextauth].ts、next/src/server/auth/ORMPrisma前端侧与 SQLModel后端侧next/prisma/schema.prisma、platform/reworkd_platform/db/数据库MySQL本仓库使用 MySQL 8.0见 docker-compose.ymldb/Dockerfile样式TailwindCSS HeadlessUInext/tailwind.config.cjs、next/src/styles/globals.cssSchema 校验Zod前端 Pydantic后端next/与platform/的 schemas 目录LLM 工具链Langchainplatform/下的 Agent 工具实现从 next/package.json 与 cli/package.json 的engines字段可以确认Node.js 版本要求为18.0.0 19.0.0部署前需确保本机 Node 版本落在此区间。架构一次部署拉起三个服务README 指出项目的自动安装 CLI 会为 AgentGPT 配置四类基础设施 环境变量与 API Key、️ 数据库MySQL、 后端FastAPI、 前端Next.js。其中「环境变量 数据库 后端 前端」的最终落点就是 docker-compose.yml 中定义的三个容器服务frontendNext.js 前端容器端口3000:3000用户通过浏览器访问http://localhost:3000与之交互构建上下文为 next/next/Dockerfile并以 volume 挂载next/.env提供运行时配置。platformFastAPI 后端端口8000:8000承载 Agent 的执行引擎与工具调用构建时使用target: prod见 platform/Dockerfile通过env_file: next/.env读取环境变量并显式注入REWORKD_PLATFORM_DB_*数据库连接参数。agentgpt_dbMySQL 8.0镜像mysql:8.0主机端口3308映射到容器内3307MYSQL_TCP_PORT: 3307并指定--character-set-serverutf8mb4 --collation-serverutf8mb4_unicode_ci以支持完整的 Unicode 字符集数据通过命名卷agentgpt_db持久化。三者的依赖关系在 compose 文件中以depends_on声明platform 依赖 agentgpt_dbfrontend 与 platform 共享同一个next/.env配置源。这意味着本地部署只需维护一份环境变量文件即可同时驱动前后端与数据库。开始之前环境与密钥准备README 明确列出了部署前置条件逐个核对后再执行安装脚本可以避免绝大多数踩坑代码编辑器任选例如 VS Code。Node.js下载并安装注意版本需满足18 19见 cli/package.json 的 engines 声明。Git用于克隆仓库。Docker安装 Docker Desktop 后需要注册账号、打开 Docker 应用并登录——后续docker-compose up --build依赖 Docker 守护进程正常运行。OpenAI API Key必需以sk-开头的密钥Agent 的大模型推理依赖它。Serper API Key可选来自 serper.dev用于启用 Google 网页搜索类工具不配置则禁用 web search。Replicate API Token可选以r8_开头README 与 CLI 提示均说明不配置时图片生成会回退到仅使用 DALL-E。这些密钥会通过安装脚本的交互问答写入环境变量文件详见下文并分别落到REWORKD_PLATFORM_OPENAI_API_KEY、REWORKD_PLATFORM_SERP_API_KEY、REWORKD_PLATFORM_REPLICATE_API_KEY三个变量中见 .env.example。一键部署运行内置 CLI 安装脚本README 的 Getting Started 章节给出了标准的四步流程。整个安装过程的核心是仓库自带的CLI 自动化配置脚本它负责完成环境变量含 API Key的写入与校验。第一步打开编辑器与终端。在编辑器如 VS Code的 Terminal 面板中执行命令Windows 下为Ctrl Mac 下为Control 。第二步克隆仓库并进入目录。克隆本项目后进入根目录git clone https://gitcode.com/gh_mirrors/ag/AgentGPT.git cd AgentGPT第三步运行安装脚本。Mac / Linux 用户./setup.shWindows 用户./setup.bat从 setup.sh 与 setup.bat 的源码可以看到这两个脚本做的事情完全一致cd cli进入 CLI 子目录 →npm install安装 CLI 依赖 →npm run start启动交互式配置程序对应 cli/package.json 的start脚本即node src/index.js。第四步跟随脚本提示完成配置。填入对应的 API Key待所有服务启动后在浏览器访问http://localhost:3000即可。CLI 的交互流程新环境 vs 已有环境进入 cli/src/index.js 可以看到 CLI 的分支逻辑脚本首先通过doesEnvFileExist()检测next/.env是否已存在cli/src/envGenerator.js 中ENV_PATH ../next/.env不存在 → 新环境流程依次询问「以何种方式运行」与三个 API Key随后调用generateEnv()生成环境变量文件已存在 → 已有环境流程打印「Existing ./next/env file found. Validating...」并调用testEnvFile()校验现有文件校验通过后见 cli/src/questions/existingEnvQuestions.js再次询问运行方式。testEnvFile()cli/src/envGenerator.js的校验逻辑值得注意它会将现有.env中非注释、非空行的变量名与预期定义逐一比对若发现缺失键会明确列出所有缺失项如- ❌ NEXTAUTH_SECRET并建议「删除 .env 文件后重新运行脚本」来重建。这是排查环境变量不全问题的最直接手段。API Key 的本地校验CLI 不只是收集密钥还会做格式校验 在线可用性校验见 cli/src/questions/newEnvQuestions.js且允许留空跳过密钥格式正则在线校验方式OpenAI Key^sk-[a-zA-Z0-9]{48}$携带Authorization: Bearer请求https://api.openai.com/v1/modelsSerper Key^[a-zA-Z0-9]{40}$携带X-API-KEY向https://google.serper.dev/search发一条q: apple inc测试查询Replicate Token^r8_[a-zA-Z0-9]{37}$携带Token请求 Replicate 的 hello-world 模型接口任何一项校验失败都会提示重新输入三项全部留空也能继续但会得到功能受限无推理/无搜索/无 Replicate 图片生成的实例。环境变量文件的生成原理generateEnv()cli/src/envGenerator.js会根据「运行方式」这一选择动态决定两个关键值这是理解本地部署端口差异的核心数据库端口dbPort选择 docker-compose 方式时为3307容器内 MySQL 端口选择手动方式时为3306本机 MySQL 默认端口后端地址platformUrldocker-compose 方式下前端访问http://host.docker.internal:8000手动方式下为http://localhost:8000。同时 CLI 会调用generateAuthSecret()用crypto.randomBytes(32)生成一个随机的 Base64 字符串作为NEXTAUTH_SECRETcli/src/envGenerator.js避免使用弱默认值。最终saveEnvFile()会把同一份内容同时写入next/.env与platform/.envcli/src/envGenerator.js保证前后端配置一致。环境变量全解CLI 生成的环境变量文件与仓库根目录的 .env.example 结构一致按注释分节解释如下# Platform Config: (max loops determines how many times the agent may execute) NEXT_PUBLIC_MAX_LOOPS100 REWORKD_PLATFORM_MAX_LOOPS${NEXT_PUBLIC_MAX_LOOPS} # Deployment Environment: NODE_ENVdevelopment NEXT_PUBLIC_VERCEL_ENV${NODE_ENV} # NextJS: NEXT_PUBLIC_BACKEND_URLhttp://localhost:8000 # Next Auth config: NEXTAUTH_SECRETchangeme NEXTAUTH_URLhttp://localhost:3000 # Auth providers (Use if you want to get out of development mode sign-in): GOOGLE_CLIENT_ID*** GOOGLE_CLIENT_SECRET*** GITHUB_CLIENT_ID*** GITHUB_CLIENT_SECRET*** DISCORD_CLIENT_SECRET*** DISCORD_CLIENT_ID*** # Backend: REWORKD_PLATFORM_ENVIRONMENT${NODE_ENV} REWORKD_PLATFORM_FF_MOCK_MODE_ENABLEDfalse REWORKD_PLATFORM_OPENAI_API_KEYchangeme REWORKD_PLATFORM_FRONTEND_URLhttp://localhost:3000 REWORKD_PLATFORM_RELOADtrue REWORKD_PLATFORM_OPENAI_API_BASEhttps://api.openai.com/v1 REWORKD_PLATFORM_SERP_API_KEYchangeme REWORKD_PLATFORM_REPLICATE_API_KEYchangeme REWORKD_PLATFORM_SID_CLIENT_IDchangeme REWORKD_PLATFORM_SID_CLIENT_SECRETchangeme REWORKD_PLATFORM_SID_REDIRECT_URIhttp://localhost:8000/api/auth/sid/callback # Database (Backend): REWORKD_PLATFORM_DATABASE_USERreworkd_platform REWORKD_PLATFORM_DATABASE_PASSWORDreworkd_platform REWORKD_PLATFORM_DATABASE_HOSTagentgpt_db REWORKD_PLATFORM_DATABASE_PORT3307 REWORKD_PLATFORM_DATABASE_NAMEreworkd_platform REWORKD_PLATFORM_DATABASE_URLmysql://${REWORKD_PLATFORM_DATABASE_USER}:${REWORKD_PLATFORM_DATABASE_PASSWORD}${REWORKD_PLATFORM_DATABASE_HOST}:${REWORKD_PLATFORM_DATABASE_PORT}/${REWORKD_PLATFORM_DATABASE_NAME} # Database (Frontend): DATABASE_USERreworkd_platform DATABASE_PASSWORDreworkd_platform DATABASE_HOSTagentgpt_db DATABASE_PORT3307 DATABASE_NAMEreworkd_platform DATABASE_URLmysql://${DATABASE_USER}:${DATABASE_PASSWORD}${DATABASE_HOST}:${DATABASE_PORT}/${DATABASE_NAME}各组变量的作用与要点执行轮数MAX_LOOPS.env.example的注释明确说明——「max loops determines how many times the agent may execute」即限制 Agent 最多执行任务的次数默认100。前后端通过NEXT_PUBLIC_MAX_LOOPS与REWORKD_PLATFORM_MAX_LOOPS共享同一值。部署环境NODE_ENVdevelopmentREWORKD_PLATFORM_ENVIRONMENT与NEXT_PUBLIC_VERCEL_ENV均引用它保持三处一致。Next.js 配置NEXT_PUBLIC_BACKEND_URL指向前端调用的后端地址docker-compose 模式下 CLI 会改写为http://host.docker.internal:8000。Next AuthNEXTAUTH_SECRET是会话签名密钥CLI 自动生成随机值手动配置请勿使用默认的changemeNEXTAUTH_URL为前端地址。第三方登录可选GOOGLE_*、GITHUB_*、DISCORD_*用于「脱离 development 模式登录」——即默认开发模式下不需要它们想启用 OAuth 登录时再填入对应平台的 Client ID / Secret。对应实现见 next/src/server/auth/ 与 next/src/pages/api/auth/[...nextauth].ts。后端密钥REWORKD_PLATFORM_OPENAI_API_KEY为必填的大模型密钥REWORKD_PLATFORM_OPENAI_API_BASE默认指向https://api.openai.com/v1如使用兼容 OpenAI 协议的代理可在此替换SERP与REPLICATE留空即禁用对应工具SID_*为可选能力预留项。数据库前后端各自维护一组DATABASE_*变量最终拼成mysql://user:passhost:port/name格式的DATABASE_URL。docker-compose 模式下host为容器服务名agentgpt_db、端口3307手动模式下 CLI 会生成端口3306并需要本机 MySQL 服务。两种运行方式Docker Compose 与手动模式CLI 的第一个问题就是选择运行方式见 cli/src/questions/sharedQuestions.js默认推荐docker-compose方式一Docker Compose推荐选择该选项后CLI 会在环境变量生成完毕后自动执行docker-compose up --buildcli/src/index.js。正如前文架构一节所述docker-compose.yml 会依次构建并启动 frontend、platform、agentgpt_db 三个服务前端监听3000端口、后端监听8000端口、MySQL 数据卷持久化于agentgpt_db卷。整个过程无需手动安装 Node 依赖或 Python 环境是 README 推荐的部署路径。方式二手动运行不推荐若在 CLI 中选择manual脚本不会拉起容器而是打印三条指引cli/src/index.js需要手动执行进入next目录运行前端cd next npm install npm run dev注意 next/package.json 的postinstall钩子会自动执行prisma generate因此无需手动处理 Prisma Client 的生成。进入platform目录运行后端cd platform poetry install poetry run python -m reworkd_platform使用或更新 env 文件中的 MySQL 数据库配置即上文数据库分节的变量。手动方式适合已有本机 MySQL端口3306与完整 Python/Node 开发环境的场景但需要自行保证三者的配置对齐因此 README 与 CLI 均将其标注为「Not recommended」。验证部署与访问无论哪种方式部署成功后的访问入口都是一致的前端界面浏览器打开http://localhost:3000。README 描述的核心体验就在这里——给 Agent 命名、设定目标观察它自主拆解并执行任务。后端服务http://localhost:8000前端所有 Agent 执行请求的中转与执行引擎。若页面表现异常优先检查next/.env与platform/.env中的REWORKD_PLATFORM_OPENAI_API_KEY、REWORKD_PLATFORM_DATABASE_*等关键值并可用testEnvFile()的缺键清单重新运行./setup.sh触发校验定位问题。仓库还提供了可选的进阶配置文档供部署后查阅例如 API Key 管理docs/developers/api-keys.mdx、SDK 接入docs/developers/sdk.mdx与文件下载docs/features/file-downloads.mdx等。小结AgentGPT 的本地部署链路可以浓缩为一句话运行 setup.sh或 setup.bat→ CLI 交互式收集并校验 API Key → 生成next/.env与platform/.env→ 通过 docker-compose.yml 拉起 Next.js 前端、FastAPI 后端与 MySQL 数据库 → 访问http://localhost:3000。理解这条链路不仅能在几分钟内跑通一个浏览器内可用的自主 AI Agent 实例也能在修改运行方式docker-compose/manual、调整执行轮数MAX_LOOPS、接入第三方登录或切换数据库连接时精准定位每一处配置的落点与影响范围。【免费下载链接】AgentGPT Assemble, configure, and deploy autonomous AI Agents in your browser.项目地址: https://gitcode.com/gh_mirrors/ag/AgentGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考