第一章 认识 AutoGPT

什么是 AutoGPT？

AutoGPT 是一个开源的 AI Agent 平台，旨在帮助用户构建、部署和运行自主 AI 智能体。不同于传统的聊天机器人，AutoGPT 能够自主分解任务、调用工具、执行操作并迭代优化，最终完成复杂的工作目标。

AutoGPT 项目由 Significant Gravitas 团队发起，是 GitHub 上增长最快的 AI 开源项目之一。自 2023 年推出以来，AutoGPT 已从单一的实验性 CLI 工具发展为成熟的平台级产品，支持可视化工作流编辑、多 Agent 协同、丰富的第三方集成等企业级功能。

核心特性

• 可视化 Agent 构建器 - 拖拽式工作流编辑器，无需编程即可创建复杂 Agent
• 168+ 内置 Block - 丰富的功能模块，覆盖文本处理、数据操作、API 调用、文件操作等
• 多 LLM 支持 - 集成 OpenAI、Anthropic、Groq、Together AI、Ollama 等多种模型提供商
• 多 Agent 协作 - 支持 Agent 间通信和任务编排
• Block 市场 - 社区贡献的 Block 可一键安装使用
• 自定义 Block SDK - 用 Python 编写你自己的 Block
• 企业级架构 - 基于 RabbitMQ、Redis、PostgreSQL 的微服务架构
• Supabase 认证 - 内置用户管理、API key 管理和权限控制

系统要求

AutoGPT 版本对比

💡 本教程聚焦 AutoGPT Platform（平台版），这是目前官方推荐的生产级部署方案。

第二章 快速上手（5 分钟）

最快的体验方式：使用官方一键安装脚本。整个过程只需几分钟。

一键安装

在终端中执行以下命令：

curl -fsSL https://setup.agpt.co/install.sh -o install.sh && bash install.sh

该脚本会自动完成以下操作：

• 检测 Docker 和 Docker Compose 是否安装
• 克隆最新版 AutoGPT 仓库
• 生成必要的 .env 配置文件
• 启动所有 Docker 服务

首次启动

安装完成后，访问以下地址：

创建管理员账号

首次访问 http://localhost:3000 时，系统会引导你创建管理员账号。此账号信息配置在根目录的 .env 文件中：

DASHBOARD_USERNAME=admin
DASHBOARD_PASSWORD=your_secure_password

💡 生产环境部署时，务必修改 DASHBOARD_PASSWORD 为强密码。

验证运行状态

使用以下命令检查所有服务是否正常运行：

docker compose ps

你应该会看到类似以下的输出，包含 frontend、rest_server、websocket_server、db 等服务均为 "Up" 状态。

第三章 Docker 部署全流程

本章介绍手动部署 AutoGPT Platform 的完整步骤。此方法适用于需要自定义配置的场景。

第一步：克隆仓库

git clone https://github.com/Significant-Gravitas/AutoGPT.git
cd AutoGPT/autogpt_platform

第二步：配置环境变量

cp .env.default .env

这会复制一份包含所有必需环境变量的模板文件。.env.default 包含了约 130 个预配置的环境变量（主要来自 Supabase），包括：

• 数据库配置：POSTGRES_PASSWORD、POSTGRES_HOST、POSTGRES_DB、POSTGRES_PORT
• 认证配置：JWT_SECRET、ANON_KEY、SERVICE_ROLE_KEY
• 面板配置：DASHBOARD_USERNAME、DASHBOARD_PASSWORD
• 加密配置：SECRET_KEY_BASE、VAULT_ENC_KEY
• API 网关：KONG_HTTP_PORT=8000、KONG_HTTPS_PORT、SITE_URL

编辑 .env 文件，将以下值修改为你自己的配置：

• DASHBOARD_PASSWORD - 设置一个强密码
• JWT_SECRET - 生成一个随机字符串

第三步：配置后端 LLM 密钥

进入 backend 目录配置 LLM 提供商密钥：

cd backend
cp .env.default .env

编辑 backend/.env，设置你的 LLM API 密钥（至少配置一个）：

DATABASE_URL=postgresql://...
REDIS_URL=redis://...
RABBITMQ_HOST=rabbitmq
ENCRYPTION_KEY=your_generated_encryption_key
OPENAI_API_KEY=sk-your-openai-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
# 可选的其他提供商
together_api_key=
groq_api_key=
codestral_api_key=

💡 必须生成 ENCRYPTION_KEY。可以使用命令：openssl rand -hex 32 生成一个 64 字符的十六进制字符串。

第四步：启动所有服务

返回平台根目录并启动服务：

cd ..
docker compose up -d --build

此命令将构建并启动所有必需的微服务：

• frontend - Web 用户界面（端口 3000）
• rest_server - REST API 服务（端口 8006）
• websocket_server - WebSocket 实时通信（端口 8001）
• db - PostgreSQL 数据库
• redis-0, redis-1, redis-2 - Redis 集群（任务队列和缓存）
• redis-init - Redis 初始化服务
• falkordb - FalkorDB 图数据库
• rabbitmq - 消息队列
• migrate - 数据库迁移（一次性服务）
• executor - Agent 执行器
• copilot_executor - Copilot 辅助执行器
• database_manager - 数据库管理服务
• scheduler_server - 定时任务调度
• notification_server - 通知服务
• clamav - 病毒扫描服务
• kong - API 网关（端口 8000）
• auth - Supabase 认证服务

第五步：查看日志

监控启动过程：

docker compose logs -f

等待 migrate 服务完成数据库迁移后，即可访问 http://localhost:3000。

第六步：停止服务

docker compose down

第四章 配置详解

.env 文件结构

AutoGPT Platform 包含两层配置文件：

1. 根目录 .env（在 autogpt_platform/ 下）- 包含全局配置和 Supabase 相关变量
2. backend/.env（在 autogpt_platform/backend/ 下）- 包含后端服务配置和 LLM API 密钥

根目录 .env 关键变量

backend/.env 关键变量

💡 模型选择（如 GPT-4o、Claude 3.5 Sonnet 等）是在 Web UI 中配置的，不在 .env 文件中设置。登录后端面板后，可以在 Agent 编辑器中为每个工作流选择模型。

LLM 提供商配置

AutoGPT Platform 支持以下 LLM 提供商，在 backend/.env 中配置对应的 API Key：

• OpenAI - 设置 OPENAI_API_KEY，支持 GPT-4o、GPT-4o-mini、o1 等
• Anthropic - 设置 ANTHROPIC_API_KEY，支持 Claude 3.5 Sonnet、Claude 3 Haiku 等
• Groq - 设置 groq_api_key，支持 Llama 3、Mixtral 等开源模型
• Together AI - 设置 together_api_key，提供多种开源模型
• Codestral - 设置 codestral_api_key，Mistral 的代码模型
• Ollama - 本地运行的开源模型（需额外配置连接）

Supabase 认证设置

AutoGPT 使用 Supabase 提供用户认证和 API 密钥管理。首次启动后：

1. 访问 http://localhost:3000
2. 使用 .env 中配置的 DASHBOARD_USERNAME 和 DASHBOARD_PASSWORD 登录
3. 在 Settings 页面可以管理 API 密钥
4. 可以在 Supabase 后台（Kong 代理的 http://localhost:8000）管理用户和权限

第五章 可视化 Agent 构建器

什么是 Block 系统？

AutoGPT 的核心创新在于其 Block 系统。Block 是构建 Agent 工作流的基本功能单元，每个 Block 封装了特定的能力——例如调用 LLM、处理文本、读取文件、发送 HTTP 请求等。用户通过拖拽和连接这些 Block，即可构建复杂的 Agent 行为，无需编写代码。

目前平台内置了 168+ 个 Block，涵盖以下类别：

• LLM Blocks - 调用各大语言模型进行文本生成、对话、推理
• Input/Output Blocks - 用户输入、文件读取、结果显示
• Text Blocks - 文本分割、拼接、模板渲染、正则匹配
• Code Blocks - 执行 Python、JavaScript 代码
• Data Blocks - JSON 解析、CSV 处理、数据转换
• API Blocks - HTTP 请求、Webhook 触发
• Logic Blocks - 条件判断、循环、分支
• Integration Blocks - 与第三方服务集成

工作流编辑器

工作流编辑器是构建 Agent 的可视化界面，核心操作：

1. 添加 Block - 从左侧面板拖拽 Block 到画布
2. 连接 Block - 从输出端口拖线到输入端口
3. 配置参数 - 点击 Block 设置其参数（如 prompt、model 等）
4. 测试运行 - 点击 Run 按钮测试当前工作流
5. 发布部署 - 保存并发布为可调用的 Agent
6. 定时调度 - 配置 cron 表达式定时执行

Block 市场

AutoGPT 提供了 Block 市场（Marketplace），用户可以浏览、安装社区贡献的 Block。通过市场，你可以快速扩展 Agent 能力，无需自己开发。

自定义 Block 开发（SDK）

你可以使用 Python 编写自定义 Block。官方 SDK 的导入方式为：

from backend.blocks._base import Block

💡 注意导入路径是 backend.blocks._base，而不是 autogpt.blocks。

一个基本的自定义 Block 模板：

from backend.blocks._base import Block, BlockCategory, BlockInput, BlockOutput

class MyCustomBlock(Block):
    """这是我的自定义 Block"""
    
    name = "my_custom_block"
    display_name = "我的自定义 Block"
    category = BlockCategory.CUSTOM
    
    def run(self, input_data: BlockInput) -> BlockOutput:
        # 处理逻辑
        result = self.process(input_data)
        yield "output", result

第六章 实战场景

场景一：智能内容摘要机器人

构建一个自动抓取网页内容并生成摘要的 Agent。

工作流程：

1. Input Block 接收 URL
2. HTTP Request Block 抓取网页内容
3. Text Block 提取主要文本（去除 HTML 标签）
4. LLM Block（使用 GPT-4o）生成 200 字摘要
5. Output Block 显示结果

测试命令： 在 Agent 界面输入目标 URL，点击运行即可。

场景二：多语言翻译与润色工作流

构建一个支持多语言翻译和文本润色的 Agent。

工作流程：

1. Input Block 接收源文本和目标语言
2. LLM Block 1 进行初步翻译
3. LLM Block 2（使用不同模型）进行润色和本地化
4. Text Block 对比前后差异
5. Output Block 输出最终结果

场景三：定时数据监控与告警 Agent

构建一个定时检查 API 数据并在异常时发送通知的 Agent。

工作流程：

1. Scheduler Block 配置每 5 分钟触发
2. HTTP Request Block 请求监控 API
3. Data Block 解析 JSON 响应
4. Logic Block 判断数据是否超出阈值
5. 如果异常：LLM Block 生成告警消息 + Notification Block 发送通知
6. 如果正常：Log Block 记录日志

场景四：SEO 文章批量生成

构建一个从关键词到完整 SEO 文章的自动化工作流。

工作流程：

1. Input Block 输入关键词列表
2. Loop Block 遍历每个关键词
3. LLM Block 1 生成文章大纲
4. LLM Block 2 撰写完整文章
5. LLM Block 3 生成 SEO 标题和 Meta 描述
6. Output Block 输出格式化结果

场景五：代码审查助手

构建一个自动审查 Pull Request 代码的 Agent。

工作流程：

1. Input Block 接收代码 diff
2. LLM Block（使用 Codestral）分析代码质量
3. LLM Block 2 检查安全漏洞
4. Text Block 格式化审查报告
5. Output Block 输出审查结果

第七章 进阶技巧

性能优化与扩展

• 增加 Redis 节点 - 在 docker-compose.yml 中扩展 redis 集群，提升任务队列吞吐量
• 调整 executor 副本数 - 使用 docker compose up -d --scale executor=3 增加执行器实例
• 数据库优化 - 为 PostgreSQL 配置合适的 shared_buffers 和 work_mem 参数
• 资源限制 - 在 docker-compose.yml 中为每个服务设置 CPU 和内存限制

安全最佳实践

• 修改默认密码 - 务必修改 DASHBOARD_PASSWORD 和 POSTGRES_PASSWORD
• 使用 HTTPS - 配置 Kong 网关使用有效的 SSL 证书
• API 密钥轮换 - 定期更换 JWT_SECRET 和 ENCRYPTION_KEY
• 网络隔离 - 将敏感服务（db、redis）限制在内部网络中
• ClamAV 扫描 - 自动对上传文件进行病毒扫描（默认启用）

自定义 Block 开发最佳实践

• 使用 backend.blocks._base import Block 作为基类
• 为 Block 定义明确的输入输出类型
• 在 run() 方法中使用 yield 返回结果
• 添加适当的错误处理和日志
• 发布到 Block 市场供团队使用

成本控制

• 模型选择 - 简单任务使用 GPT-4o-mini 或 Claude 3 Haiku 替代旗舰模型
• 缓存策略 - 对重复的 LLM 请求使用 Redis 缓存
• 超时设置 - 为 LLM 调用设置合理的超时时间，避免无限等待
• 本地模型 - 使用 Ollama 运行开源模型（如 Llama 3）减少 API 费用
• 批处理 - 合并多个小任务为一次 LLM 调用

监控与日志

• 使用 docker compose logs 查看各服务日志
• 在 Web UI 的 Agent Runs 页面查看每个工作流的执行记录
• 配置外部监控（如 Prometheus + Grafana）监控系统指标

第八章 常见问题与排错

问题 1：docker compose up 后服务无法启动

原因： 端口冲突或 Docker 资源不足。

解决方法：

• 检查 3000、8000、8006 等端口是否被占用：lsof -i :3000
• 增加 Docker 资源限制：在 Docker Desktop 设置中分配更多内存
• 查看具体错误：docker compose logs <service_name>

问题 2：migrate 服务一直失败

原因： 数据库连接问题或配置错误。

解决方法：

• 确认 DATABASE_URL 配置正确
• 确认 POSTGRES_PASSWORD 在根目录 .env 和 backend/.env 中一致
• 重启数据库服务：docker compose restart db
• 检查迁移日志：docker compose logs migrate

问题 3：登录页面无法加载（localhost:3000 白屏）

原因： Supabase 认证服务未就绪。

解决方法：

• 确认 kong 和 auth 服务已启动：docker compose ps
• 检查 frontend 日志：docker compose logs frontend
• 等待 1-2 分钟让所有服务完成初始化

问题 4：Agent 运行时提示 "No LLM configured"

原因： 未配置 LLM API 密钥。

解决方法：

• 确认 backend/.env 中设置了 OPENAI_API_KEY 或其他提供商密钥
• 在 Web UI 的 Agent 编辑器中选择了正确的模型
• 重启 backend 服务：docker compose restart rest_server executor

问题 5：数据库连接超时

原因： db 服务启动较慢，其他服务过早尝试连接。

解决方法：

• 等待 30 秒后重试
• 重启所有服务：docker compose down && docker compose up -d --build
• 检查 POSTGRES_HOST 是否设置为 db（Docker 内部主机名）

问题 6：git clone 速度慢或失败

原因： 网络问题或仓库过大。

解决方法：

• 使用代理或镜像：git clone https://mirror.ghproxy.com/https://github.com/Significant-Gravitas/AutoGPT.git
• 使用浅克隆：git clone --depth 1 https://github.com/Significant-Gravitas/AutoGPT.git

问题 7：docker compose 命令找不到

原因： Docker Compose 未安装或版本过低。

解决方法：

• 安装最新版 Docker Desktop（包含 Docker Compose v2）
• 或单独安装：sudo apt install docker-compose-plugin
• 确认版本：docker compose version

问题 8：WebSocket 连接断开

原因： websocket_server 服务未正确启动或网络问题。

解决方法：

• 检查 websocket_server 日志：docker compose logs websocket_server
• 确认 RABBITMQ_HOST 配置正确
• 重启 websocket_server：docker compose restart websocket_server

问题 9：Block 市场无法加载

原因： 网络问题或市场服务不可用。

解决方法：

• 检查网络连接是否能访问 GitHub
• 确认 SITE_URL 配置正确
• 查看 rest_server 日志获取详细信息

问题 10：运行 Agent 时出现 "Encryption key invalid" 错误

原因： ENCRYPTION_KEY 未生成或格式不正确。

解决方法：

• 使用 openssl rand -hex 32 生成一个新的加密密钥
• 更新 backend/.env 中的 ENCRYPTION_KEY
• 重启所有服务：docker compose down && docker compose up -d --build

问题 11：镜像构建失败（--build 阶段出错）

原因： 网络问题导致依赖下载失败。

解决方法：

• 重试构建：docker compose up -d --build
• 检查 Docker 网络：docker network ls
• 设置 Docker 镜像加速器（中国大陆用户）

💡 遇到未列出的问题，首先检查对应服务的日志：docker compose logs <service_name> -f。常见服务名：frontend、rest_server、executor、migrate、db。

附录：命令参考表

安装与部署

密钥生成

服务端口

Docker 服务列表

Block 开发