AutoGPT 本地部署踩坑记：从装不上到真正跑起来

折腾了一天 AutoGPT Platform，把安装、启动和一堆莫名其妙的坑都趟了一遍。这篇不是官方教程的复读，是我自己踩出来的经验，按「搭建环境 → 运行起来 → 遇到的坑」三部分写，希望能帮你少走点弯路。

官方项目地址：https://github.com/Significant-Gravitas/AutoGPT
官方项目文档：https://agpt.co/docs/platform/

一、搭建环境

1. 前置条件

动手之前先确认这几样齐了：

• Git：用来拉代码
• Node.js + npm：前端要跑，node -v、npm -v 能出版本号就行
• Docker + Docker Compose：整个平台靠它编排一堆容器

Windows 用户特别注意：装 Docker 时一定选 WSL 2 后端，别用 Hyper-V。官方文档里明确说了，Hyper-V 会导致数据库容器健康检查失败，你会白折腾一小时才发现问题出在这。

2. 拉代码

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

仓库比较大，等一会儿正常。进去之后你会发现里面有两条产品线：一个是 2023 年那个命令行版 AutoGPT Classic，另一个才是我们要装的 AutoGPT Platform（可视化拖拽搭 Agent 的那个）。别跑错目录。

3. 进平台目录、配环境变量

cd AutoGPT/autogpt_platform
cp .env.default .env

.env 里存了数据库密码、API Key、服务端口这些。本地开发用默认值就能跑，但有两件事建议你顺手做掉：

• 换掉加密密钥：默认密钥是公开的，自己玩无所谓，要长期用建议换一下（用 Python 的 cryptography 或 poetry run cli gen-encrypt-key 生成新的）
• 千万别把 .env 提交到 git，里面是敏感信息

4. 硬件心里有个数

官方没写硬件要求，但实测下来：8GB 内存起步，16GB 才舒服。整套平台会拉起十几个容器，镜像好几个 G，磁盘留个 20G 以上比较稳。

二、运行起来

1. 启动

docker compose up -d --build

第一次跑要编译前端和后端镜像，5-10 分钟很正常，耐心等。

2. 访问

浏览器打开 http://localhost:3000，应该能看到登录/注册页。

3. 端口都是干嘛的

4. 改了 .env 之后

改完 .env 不是重启所有容器，只重启相关的就行：

docker compose up -d rest_server copilot_executor

但如果你改的是前端相关的 NEXT_PUBLIC_* 变量，必须重新 build 前端镜像才生效，光重启没用。这个坑后面会细说。

三、遇到的坑

下面按我踩的顺序写，每个都是「现象 → 原因 → 怎么解决」。

坑 1：登不进去，后端服务全退

现象：页面打不开，报错一堆，后端服务起不来。

原因：Redis 集群状态异常（cluster_state:fail），连带着后端服务全挂了。前端那边还会报 EAI_AGAIN rest_server，看着像网络问题，其实根子在这。

解决：强制重建 Redis 集群，再把后端拉起来：

docker compose up -d --force-recreate redis-0 redis-1 redis-2 redis-init

坑 2：端口被占（尤其是开着 Dify）

现象：启动报 port is already allocated。

原因：这套平台占用的端口特别多——3000、8000、8006、5432、5672、17000-17002、6380、3310……只要你机器上跑着别的开发服务，很容易撞车。我这边就是被 Dify 占了端口。

解决：两个办法：

• 关掉占端口的服务再启动
• 或者用 docker-compose.override.yml 改端口映射。别直接改官方那个 compose 文件，下次 git pull 就被覆盖了；override 文件会自动合并，改这里才持久。

坑 3：注册/初始化报 401（跨域 cookie 问题）

现象：Failed to initialize onboarding，一部分接口报 401，一部分正常。

原因：前端请求 API 时写死了绝对地址 http://localhost:3000/api/proxy。你要是用局域网 IP（比如 http://192.168.1.100:3000）打开页面，这个 localhost 地址就变成跨域了，cookie 带不过去，于是 401。

解决：把前端请求代理改成同源相对路径 /api/proxy，并让请求带上 cookie（credentials: "include"）。改的是这个文件：

frontend/src/app/api/mutators/custom-mutator.ts

坑 4：局域网访问连不上（SSE / WebSocket 用不了 localhost）

现象：Could not start a new chat session、Connection lost。

原因：SSE 和 WebSocket 直连的是 localhost:8006、localhost:8001，用局域网 IP 打开页面时这些 localhost 地址全都连不上，CORS 也没放行局域网来源。

解决：新建 frontend/.env，把直连地址都换成局域网 IP：

BETTER_AUTH_URL=http://192.168.1.100:3000
NEXT_PUBLIC_FRONTEND_BASE_URL=http://192.168.1.100:3000
NEXT_PUBLIC_AGPT_SERVER_URL=http://192.168.1.100:8006/api
NEXT_PUBLIC_AGPT_WS_SERVER_URL=ws://192.168.1.100:8001/ws

注意：NEXT_PUBLIC_* 这些变量会打进前端镜像，改完必须 rebuild 前端，光重启没用。

坑 5：发消息没反应，一直"Connection lost"（最坑的一个）

现象：新建会话后发第一条消息，页面立刻弹 Connection lost / Reconnecting…，输入框被锁死，模型永远不回复。后端日志里只看到建会话的请求，真正发消息的接口一次都没到。

原因：两个问题叠在一起：

1. crypto.randomUUID 在 HTTP 局域网下不可用。这个 API 只在 HTTPS 或 localhost（安全上下文）下存在。你用 http://192.168.1.100:3000 打开页面时，发消息请求体里生成 id 的那行代码直接抛错，请求在浏览器里就失败了，根本没发出去。前端把它当成断网，于是弹 Connection lost。

2. 空会话被误判断线。新会话的流程是「建会话 → 页面重挂载 → 补发暂存的第一条消息」，一旦出错进入重连状态，重连提示会把这条暂存消息永远拦住。

解决：写一个 generateUuid()，安全上下文用 crypto.randomUUID()，否则用 crypto.getRandomValues() 手工拼一个 UUIDv4，然后把发消息的地方都改用它。同时调整重连逻辑：会话里还没有任何用户消息时，重连状态不再拦截发送。涉及这几个文件：

frontend/src/lib/utils.ts
frontend/src/app/(platform)/copilot/copilotStreamTransport.ts
frontend/src/app/(platform)/copilot/useCopilotPendingChips.ts
frontend/src/app/(platform)/copilot/helpers.ts
frontend/src/app/(platform)/copilot/useCopilotReconnect.ts
frontend/src/app/(platform)/copilot/useCopilotStream.ts
frontend/src/app/(platform)/copilot/useSendMessage.ts

改完重新 build 前端：

docker compose build frontend && docker compose up -d frontend

坑 6：对话能通，但要好几分钟才回复

现象：消息发出去了，但等了 3 分钟才回，还弹 Connection timed out。

原因：本地模型（vLLM）一轮推理就要 200 多秒，而前端重连超时只设了 30 秒。这是误报，不是真断线，是模型太慢超过了前端等待时间。

解决：模型侧慢是硬伤，可以换更快的模型，或者接受这个延迟。前端超时时间要不要改，看你取舍。

坑 7：思考模型开头空白几秒

现象：用 Qwen 这类思考模型时，发完消息后开头几秒没反应。

原因：思考模型会先输出 reasoning_content（思考过程），再输出正式回答。开头那几秒空白是它在"想"，不是卡了。

解决：不用处理，等它想完自然就回了。知道是正常现象，别跟坑 5 一样误判成断线去折腾。

最后说两句

AutoGPT Platform 本身不难装，难的是局域网访问 + 本地模型这两块，几乎所有的坑都出在这。如果你只是本机 localhost 自己玩，坑 3、4、5 基本碰不到；但你要用局域网 IP 给别人访问、或者接本地 vLLM，那这篇里写的基本都会遇到。

几个通用提醒再强调一遍：

• Windows 用 WSL 2，别用 Hyper-V
• 端口冲突用 override 文件，别改官方 compose
• .env 别提交 git，加密密钥记得换
• 改前端变量要 rebuild 前端，不是重启
• 本地模型慢导致的超时，先确认是不是真断线再动手

祝一次跑通。