SuperAGI 配置教程：从环境变量到工具接入的实操步骤
SuperAGI 的配置主要围绕 .env 文件展开：填入有效的 OpenAI API Key、指定模型名称、确认数据库和 Redis 连接地址，然后通过 Docker Compose 启动前后端服务。
如果你卡在启动后无法创建智能体或工具调用失败，多数情况是环境变量没生效或网络访问受限。
先确认运行环境和获取密钥
SuperAGI 官方推荐用 Docker 运行，本地电脑和 Linux 服务器都可以。
需要提前装好 Docker 与 Docker Compose，并准备一个可用的 OpenAI API Key。
如果服务器在国内，要确认能正常访问 OpenAI 接口，否则即使配置正确，智能体也会在推理阶段超时。
拉取代码后，项目根目录通常有一个 .env.example 文件，复制成 .env 再修改：
cp .env.example .env修改 .env 中的关键配置项
用编辑器打开 .env，重点检查下面几项。
不同版本的变量名可能略有差异，以你下载的 .env.example 为准。
OPENAI_API_KEY=sk-你的真实密钥
MODEL= gpt-4o-mini
OPENAI_API_BASE=https://api.openai.com/v1
POSTGRES_URL=postgresql://superagi:superagi@postgres:5432/superagi
REDIS_URL=redis://redis:6379/0OPENAI_API_KEY 必须换成自己的密钥，不要保留示例值。MODEL 填你账号有权限调用的模型名。
如果你使用中转接口，把 OPENAI_API_BASE 改成对应地址，并确认该地址兼容 OpenAI 的 /v1/chat/completions 格式。
数据库和 Redis 的地址在 Docker Compose 网络内部使用服务名，一般不需要改。
启动服务并检查容器状态
配置保存后，在项目目录执行：
docker compose up -d启动完成后查看容器是否全部处于运行状态：
docker compose ps预期结果是后端、前端、Postgres、Redis 等容器状态为 Up。
如果某个容器反复重启，用 docker compose logs 服务名 查看报错。
常见原因是端口被占用或 .env 中数据库密码与 Compose 文件不一致。
在界面中验证模型和工具配置
浏览器访问 http://服务器IP:3000 进入 SuperAGI 界面。
首次使用需要注册账号，然后进入设置页面检查模型配置。
如果界面里没有自动读取 .env 中的密钥，可以在模型设置中手动填入 API Key 和模型名称。
创建一个测试智能体，给它一个简单任务，例如“列出三个常见的服务器监控指标”。
任务开始运行后，观察日志中是否出现模型调用记录。
能正常返回结果，说明模型配置已经生效。
工具接入是另一个容易出问题的点。
SuperAGI 的部分工具需要单独配置 API 地址或密钥，例如搜索工具、代码执行工具。
在工具管理页面启用工具后，要确认工具的服务地址是容器内可访问的地址，而不是 localhost。
如果工具调用一直失败，先检查该工具对应的环境变量是否填写正确，再确认容器网络是否能解析到目标服务。
常见报错和避坑说明
启动后页面打不开，先检查 docker compose ps 中前端容器是否运行，再确认服务器防火墙或安全组是否放行了 3000 端口。
智能体创建成功但任务一直处于等待状态，通常是模型接口不可达。
在服务器上执行 curl 测试 API 地址，确认返回状态码正常，再回看 .env 中的 OPENAI_API_BASE 是否多了或少了 /v1。
修改 .env 后必须重启服务才会生效，只重启单个容器可能不够，建议执行 docker compose down 再 docker compose up -d。
另外，不要把 .env 文件提交到公开仓库，密钥泄露后要及时在 OpenAI 后台吊销并重新生成。
如果使用外部 Postgres 或 Redis，需要把 POSTGRES_URL 和 REDIS_URL 改成实际连接地址，并确保容器内能访问。
修改数据库地址后，首次启动可能需要等待迁移完成，不要急于反复重启。
配置完成后的检查清单
确认 .env 中密钥、模型名和接口地址三项与你的账号匹配；
确认 docker compose ps 所有容器为运行状态；
在界面中成功运行一个简单任务；
检查工具调用日志没有连接拒绝或鉴权失败。
做到这四点，SuperAGI 的基础配置就算完成了。
后续接入更多工具时，沿用同样的思路：先改环境变量，再重启服务，最后看日志验证。
