1. 为什么我要在本地跑一个 AgentGPTManus 这类通用 Agent 火起来之后很多人第一反应是「能不能自己搭一个」。AgentGPT 就是目前最省事的平替路径之一它是一个开源的自主 AI 代理工具你在浏览器里输入一个目标它会自动把目标拆成子任务、生成执行计划、逐步调用模型去完成整个过程可视化展示。适合谁想理解 Agent 任务拆解逻辑的开发者、想给团队内部做一个可控 Agent 沙箱的人、以及不想把 API Key 和业务数据交给第三方托管平台的人。我这次的目标很明确在一台 Ubuntu 22.04 的开发机上用 Docker 和源码两种方式把 AgentGPT 跑起来并且把模型调用通道统一到 TaoToken 的 API 上这样 OpenAI Key 和统一 Key 两种配置都能覆盖。整篇会给出可直接复制的settings.json骨架、环境变量模板、启动命令以及从启动到第一个任务跑通的完整验证动作。安装包获取方式放在文末不绕弯子。需要提前说清楚一点AgentGPT 本身只是一个调度壳真正干活的是背后的模型。所以部署能不能成功一半取决于容器和依赖另一半取决于模型通道是否稳定、Key 是否有额度。下面按「先跑通、再定制」的顺序来。2. 部署前置环境、Key 与 TaoToken 通道2.1 环境要求与依赖清单AgentGPT 的前端是 Next.js后端是 FastAPI Prisma数据库默认 MySQL。官方推荐 Docker 一键起源码模式则需要 Node.js 18、pnpm、Python 3.10。我实测下来机器配置 2C4G 起步就够跑基础任务但如果要开多个并发 Agent内存建议 8G 以上。先把基础依赖装好Ubuntu 下大致是这样# 安装 Docker Engine已装可跳过 curl -fsSL https://get.docker.com | sh sudo usermod -aG docker $USER newgrp docker # 源码模式需要的 Node 与 pnpm node -v # 需 18 npm install -g pnpm pnpm -vWindows 和 macOS 用户直接装 Docker Desktop 即可源码模式额外装 Node 18 和 pnpm。这里有个坑pnpm 版本太新有时会和 AgentGPT 的 lockfile 冲突建议用pnpm8。2.2 模型通道OpenAI Key 与 TaoToken 统一 KeyAgentGPT 默认走 OpenAI 官方接口。如果你手上是 OpenAI Key直接填即可如果想用统一通道管理多个模型、避免在代码里散落多个 Key可以走 TaoToken 的 API 通道。它的作用是提供一个兼容 OpenAI 协议的统一入口你只需要把 base_url 指向它Key 换成 TaoToken 的 KeyAgentGPT 侧几乎不用改代码。TaoToken 官网入口在这里https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 这个不加 UTM。Key 的创建在控制台的 API Keys 页面https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到参数对不上时优先查这里。注意无论用哪种 Key都不要把 Key 硬编码进提交到 Git 的文件里。AgentGPT 的环境变量文件默认在.env记得加进.gitignore。2.3 获取项目代码git clone https://github.com/reworkd/AgentGPT.git cd AgentGPT如果你网络拉取 GitHub 慢可以用镜像或者直接下载 zip 包安装包获取方式见文末。拉下来之后先别急着setup.sh把 Key 配好再启动能少走一轮重启。3. 两条部署路径Docker 一键与源码定制3.1 Docker 路径最快跑通Docker 模式适合「先看到界面再说」的人。AgentGPT 提供了setup.shLinux/macOS和setup.batWindows脚本会自动拉镜像、起 MySQL、初始化前后端。# Linux / macOS chmod x setup.sh ./setup.sh # Windows ./setup.bat脚本跑完后默认访问地址是http://localhost:3000。但这里有个关键点脚本默认用的是 OpenAI 官方地址如果你要走 TaoToken 通道需要在启动前改环境变量。找到项目根目录的.env没有就从.env.example复制填入# .env 模板 OPENAI_API_KEYsk-你的TaoToken或OpenAI密钥 OPENAI_API_BASE_URLhttps://taotoken.net/api DATABASE_URLmysql://user:passlocalhost:3306/agentgpt NEXT_PUBLIC_BACKEND_URLhttp://localhost:8000改完再执行docker compose up -d容器会读取新的环境变量。实测下来Docker 模式最容易出问题的地方是 MySQL 容器健康检查没过导致后端连不上库日志里会刷Cant reach database server。解决办法是等 MySQL 完全起来再重启后端容器docker compose ps docker compose restart agentgpt-backend3.2 源码路径二次开发与插件扩展源码模式适合要改任务拆解逻辑、加自定义工具的人。步骤比 Docker 多但可控性强。先装依赖pnpm install然后处理 Python 侧。AgentGPT 的platform/pyproject.toml里对langchain的版本比较敏感社区反馈 0.0.344 附近最稳版本太高会出现ImportError。改完执行cd platform pip install -e .接下来是配置。源码模式下模型通道的配置集中在platform/reworkd_platform/settings.py读取的环境变量以及前端的envGenerator.js。我建议统一用一个settings.json骨架来管理避免散落{ openai: { api_key: sk-你的密钥, api_base: https://taotoken.net/api, model: gpt-3.5-turbo }, database: { url: mysql://user:passlocalhost:3306/agentgpt }, agent: { max_loops: 25, max_tokens: 4000 } }对应到环境变量模板export OPENAI_API_KEYsk-你的密钥 export OPENAI_API_BASE_URLhttps://taotoken.net/api export DATABASE_URLmysql://user:passlocalhost:3306/agentgpt export REWORKD_PLATFORM_OPENAI_API_KEY$OPENAI_API_KEY启动分两个终端# 终端 1前端 pnpm dev # 终端 2后端 cd platform python -m reworkd_platform前端默认 3000后端 8000。如果前端报NEXT_PUBLIC_BACKEND_URL未定义检查.env是否被 Next.js 正确加载必要时重启pnpm dev。3.3 两种路径对比维度Docker 模式源码模式上手速度快一条脚本慢需装依赖定制能力弱改环境变量为主强可改任务逻辑适合场景快速体验、内部演示二次开发、插件扩展常见坑MySQL 健康检查、端口占用langchain 版本、环境变量加载4. 验证从启动到第一个任务跑通4.1 启动检查Docker 模式下docker compose ps curl http://localhost:8000/api/health返回{status:ok}说明后端活着。前端打开http://localhost:3000能看到 AgentGPT 的输入框即成功。源码模式下curl http://localhost:8000/api/health如果 8000 端口没响应看后端终端有没有报数据库连接错误多半是DATABASE_URL写错或 MySQL 没起。4.2 首个任务React 学习计划在输入框里填NameReactMasterGPTGoal掌握 React 语法、核心概念及底层原理点启动后AgentGPT 会先做任务拆解通常生成 6 到 8 个子任务比如「学习 JSX 语法」「理解组件生命周期」「掌握 Hooks 机制」「对比虚拟 DOM 与原生 DOM 性能」。每个子任务会调用一次模型结果实时显示在右侧。我实测下来第一次跑最容易卡在「任务拆解」这一步界面一直转圈。原因通常是 Key 没额度或 base_url 写错。这时候看后端日志如果出现401或insufficient_quota就是 Key 的问题如果出现Connection error就是 base_url 不通。走 TaoToken 通道时确认OPENAI_API_BASE_URL结尾没有多余的斜杠正确写法是https://taotoken.net/api。4.3 结果优化任务跑完后可以继续对话微调。比如针对「理解虚拟 DOM」这个子任务追加一句「补充原生 DOM 操作与虚拟 DOM 的性能对比实验」AgentGPT 会重新规划这一步。也可以通过指令调整优先级比如「优先学习函数组件再接触类组件」。这些交互都走同一套模型通道所以 Key 的额度要留够。5. 本篇常见报错排查5.1 Docker 权限错误sudo usermod -aG docker $USER newgrp docker执行后重新登录终端否则docker compose仍会报permission denied。5.2 API 调用失败先确认 Key 有效、有额度再确认 base_url。走 TaoToken 通道时用 curl 直接测一下curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer sk-你的密钥能返回模型列表说明通道正常。如果这里就失败问题不在 AgentGPT而在 Key 或通道配置。5.3 任务中断或逻辑混乱AgentGPT 默认单次任务循环上限是 25 次复杂目标容易触发上限后中断。可以在settings.json里把max_loops调大但别无限调否则会烧额度。另一个办法是换更强的模型复杂任务用 GPT-4 级别的模型拆解质量明显更好。5.4 数据库连接失败Docker 模式下最常见。先docker compose logs mysql看 MySQL 是否启动完成再docker compose restart agentgpt-backend。源码模式下检查DATABASE_URL的账号密码和库名是否和实际一致。5.5 前端白屏多半是NEXT_PUBLIC_BACKEND_URL没配或后端没起。打开浏览器控制台看 Network如果请求 8000 端口失败就是后端问题如果请求 3000 正常但页面空检查pnpm dev终端有没有编译报错。6. 后续怎么用通道、模型与长期编码AgentGPT 跑通之后下一步通常是两件事一是把模型通道固定下来二是把它接到更长期的编码或 Agent 工作流里。通道方面如果你只是偶尔跑几个任务用模型对话页面手动验证模型是否可用就够了https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。如果你要把 AgentGPT 当成日常工具频繁调用模型建议在控制台把 Key 和额度管理好https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。接入细节对不上时查文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。如果你打算把 AgentGPT 的能力延伸到长期编码、自动化 Agent 任务可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。它更适合需要持续调用、多任务并行的场景比单次对话更省心。安装包获取方式项目源码直接在 GitHub 拉取即可如果拉取困难可以在 TaoToken 文档页的资源区找到打包好的镜像和依赖清单按文档里的校验步骤解压后对照本文第 3 节的配置启动。整个流程里最值得花时间的不是装依赖而是把 Key 和 base_url 这对配置一次配对后面所有任务都靠它。