AgentGPT 部署与模型接入配置：从环境准备到任务验证

AgentGPT 是一个可以自行部署的网页端 AI Agent 工具，配置过程主要围绕三件事：准备运行环境、填写模型 API Key、启动服务并验证任务能否正常执行。
下面按实际部署顺序说明，适合已经有一台 Linux 服务器或本地开发机、想自己跑起 AgentGPT 的读者。

部署前需要确认的环境条件

AgentGPT 依赖 Node.js 运行前端和后端，同时需要数据库保存任务和用户数据。
开始之前先确认以下条件：

• 一台可以执行命令的 Linux 服务器或本地电脑，建议内存不低于 2GB。
• 已安装 Node.js，版本建议参考项目仓库的 package.json 中 engines 字段，不要凭记忆选版本。
• 已安装包管理器，项目通常使用 npm 或 pnpm，以仓库说明为准。
• 一个可用的模型 API Key，例如 OpenAI 或兼容接口的 Key。
• 如果使用 MySQL 或 PostgreSQL，需要提前创建数据库和账号。

检查 Node.js 是否就绪：

node -v
npm -v

如果命令不存在，先安装 Node.js 再继续。
不要跳过这一步直接克隆代码，否则后续安装依赖会直接报错。

获取代码并安装依赖

把 AgentGPT 仓库克隆到服务器目录，然后进入项目目录安装依赖：

git clone <项目仓库地址> agentgpt
cd agentgpt
npm install

安装过程中如果出现网络超时，先检查服务器能否正常访问 npm 源。
部分依赖需要编译工具，Debian/Ubuntu 系统可提前安装：

sudo apt update
sudo apt install -y build-essential python3

安装完成后不要急着启动，下一步先把环境变量配好。

配置环境变量与模型接入

AgentGPT 的配置主要通过项目根目录的 .env 文件完成。
通常仓库会提供 .env.example，复制一份再修改：

cp .env.example .env

用编辑器打开 .env，重点检查以下配置项。
不同版本字段名可能略有差异，以 .env.example 中实际存在的键名为准：

# 模型 API Key
OPENAI_API_KEY=你的_API_Key

# 模型名称，按你的账号可用模型填写
OPENAI_MODEL=gpt-3.5-turbo

# 数据库连接地址
DATABASE_URL=mysql://用户名:密码@127.0.0.1:3306/agentgpt

# 服务监听端口
NEXT_PUBLIC_APP_PORT=3000

如果使用兼容 OpenAI 协议的第三方接口，还需要配置接口地址字段，常见写法是 OPENAI_API_BASE_URL 或类似名称，具体以项目文档为准。

配置时注意：

• API Key 不要加引号或多余空格，否则请求会返回鉴权失败。
• 数据库密码中如果包含 @、# 等特殊字符，需要做 URL 编码，或者改用环境变量分开传递。
• 修改 .env 后必须重启服务才会生效。

初始化数据库并启动服务

数据库连接配置好后，执行项目提供的迁移命令。
常见命令如下，具体脚本名以 package.json 的 scripts 为准：

npx prisma migrate deploy

如果项目使用其他 ORM，按仓库说明执行对应的初始化命令。
迁移成功后，启动开发服务或生产构建：

npm run dev

生产环境一般先构建再启动：

npm run build
npm start

启动后终端会提示监听地址，默认通常是 http://localhost:3000。
如果是远程服务器，需要在安全组或防火墙放行对应端口，然后用浏览器访问 http://服务器IP:3000。

验证任务能否正常执行

页面能打开不代表配置完成，还要确认 AgentGPT 能真正调用模型。
在网页中创建一个简单任务，例如“列出三种常见的 HTTP 状态码并解释含义”，观察执行过程：

• 任务能进入执行状态，说明前端与后端通信正常。
• 能返回模型生成的内容，说明 API Key 和模型名称配置正确。
• 任务记录能保存并在刷新后仍然存在，说明数据库连接正常。

如果页面打开但任务一直停在初始状态，优先查看终端日志和浏览器开发者工具的网络请求，定位是接口超时、鉴权失败还是数据库写入异常。

常见报错与避坑提醒

端口被占用：启动时报 EADDRINUSE，说明 3000 端口已被其他程序使用。
可以修改 .env 中的端口，或先停止占用端口的进程。

API 请求返回 401 或 403：检查 API Key 是否有效、是否有多余空格，以及账号是否支持所填模型。

数据库连接失败：确认数据库服务已启动、账号密码正确、DATABASE_URL 中的主机和端口可访问。
远程数据库还要检查白名单。

构建时内存不足：小内存服务器执行 npm run build 可能被系统终止，可以临时增加交换分区，或换到内存更大的环境构建。

不要直接把 .env 提交到 Git：该文件包含密钥和数据库密码，应加入 .gitignore，生产环境通过服务器环境变量或密钥管理工具注入。

上线前还需要做什么

本地跑通后，如果准备长期使用，建议把服务交给进程管理工具托管，例如 pm2，并配置反向代理和 HTTPS。
同时限制访问来源，避免 API Key 被公开页面滥用。
AgentGPT 配置教程中容易被忽略的一点是密钥安全：一旦 Key 泄露，应立刻在模型平台吊销并重新生成，而不是只改页面配置。

完成以上步骤后，AgentGPT 的部署和模型接入基本就绪。
后续如果更换模型或数据库，按同样的顺序检查环境变量、重启服务，再用一个简单任务验证即可。