> For the complete documentation index, see [llms.txt](https://docs.clore.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.clore.ai/guides/guides_v2-zh/ai-ping-tai-yu-zhi-neng-ti/superagi.md).

# SuperAGI 智能体框架

在 Clore.ai 上部署 SuperAGI——一个开发者优先的自主 AI 智能体框架，具备 GUI 仪表盘、工具市场、并发智能体，并可在强大的 GPU 云服务器上选择支持本地 LLM。

## 概览

[SuperAGI](https://github.com/TransformerOptimus/SuperAGI) 是一个开源、以开发者为先的自治 AI 智能体框架，在 GitHub 上拥有 1.5 万+ 星标。与简单聊天机器人不同，SuperAGI 运行 **自治智能体** —— 能够独立规划、执行多步骤任务、使用工具，并在无需持续人工输入的情况下不断迭代以实现目标的 AI 系统。

**为什么要在 Clore.ai 上运行 SuperAGI？**

* **可选 GPU，支持强大的本地 LLM** —— 在 Clore.ai 的 GPU 上运行由本地模型（Llama、Mistral 等）驱动的智能体，实现完全私有、成本可控的自治 AI。
* **并发智能体执行** —— 在同一台服务器上并行运行多个智能体，每个智能体同时处理不同任务。
* **持久化智能体记忆** —— 智能体会保留上下文、从工具输出中学习，并在两次运行之间将长期记忆存储到向量数据库中。
* **工具市场** —— 预置了 Google 搜索、GitHub、电子邮件、Jira、Notion 等集成。
* **Clore.ai 的经济性** —— RTX 3090 仅需 $0.07–0.21/小时，你就能以云端 AI 服务成本的一小部分运行功能强大的自治智能体。

### 主要特性

| 功能      | 描述                              |
| ------- | ------------------------------- |
| 智能体配置   | 通过 GUI 创建、配置并部署智能体              |
| 工具市场    | 30+ 内置工具（搜索、代码、文件、API）          |
| 多模型支持   | OpenAI、Anthropic、本地 LLM，支持自定义端点 |
| 并发智能体   | 同时运行多个智能体                       |
| 智能体记忆   | 短期（上下文窗口）+ 长期（向量数据库）            |
| GUI 仪表盘 | 用于智能体管理的完整 Web 界面               |
| 资源管理器   | 跟踪每个智能体的 token 使用量和成本           |
| 工作流模板   | 针对常见任务的预置智能体模板                  |

### 架构

```
┌────────────────────────────────────────────────────┐
│              SuperAGI 技术栈                       │
│                                                    │
│  ┌─────────────────────┐   ┌───────────────────┐   │
│  │  前端（端口 3000）   │   │  API（端口 8001）  │   │
│  │   Next.js 界面       │   │  FastAPI 后端     │   │
│  └──────────┬──────────┘   └─────────┬─────────┘   │
│             └──────────┬─────────────┘             │
│                        ▼                           │
│  ┌─────────────────────────────────────────────┐   │
│  │               智能体执行器                   │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  │   │
│  │  │  智能体1 │  │  智能体2 │  │ 智能体N  │  │   │
│  │  └──────────┘  └──────────┘  └──────────┘  │   │
│  └───────┬─────────────┬─────────────┬─────────┘   │
│          ▼             ▼             ▼             │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐      │
│  │ PostgreSQL │  │  Redis    │  │  向量    │      │
│  │  （状态）  │  │  （队列） │  │   DB     │      │
│  └───────────┘  └───────────┘  └───────────┘      │
└────────────────────────────────────────────────────┘
          │
    ┌─────┴──────┐
    ▼            ▼
 OpenAI      本地 LLM
 Anthropic   (Ollama/vLLM)
```

***

## 需求

### 服务器规格

| 组件      | 最低        | 推荐               | 备注               |
| ------- | --------- | ---------------- | ---------------- |
| **GPU** | 无（API 模式） | RTX 3090（本地 LLM） | 本地模型推理需要 GPU     |
| **显存**  | —         | 24 GB            | 用于运行 13B+ 本地模型   |
| **CPU** | 4 vCPU    | 8 vCPU           | 智能体执行对 CPU 要求较高  |
| **内存**  | 8 GB      | 16 GB            | 多个并发智能体需要内存      |
| **存储**  | 20 GB     | 100+ GB          | 智能体日志、向量数据库、模型存储 |

### Clore.ai 价格参考

| 服务器类型             | 大致费用                              | 使用场景                                |
| ----------------- | --------------------------------- | ----------------------------------- |
| CPU（8 vCPU，16 GB） | 约 $0.10–0.20/小时                   | SuperAGI + 外部 API（OpenAI/Anthropic） |
| RTX 3090（24 GB）   | $0.07–0.21/小时                     | SuperAGI + Ollama 13B 本地模型          |
| RTX 4090（24 GB）   | $0.14–0.42/小时                     | SuperAGI + Ollama，更快推理              |
| 2× RTX 3090       | $0.14–0.42/小时                     | SuperAGI + 70B 模型（Q4 量化）            |
| A100 80 GB        | [裸机](https://clore.ai/bare-metal) | SuperAGI + 大型模型，高并发                 |
| H100 80 GB        | 约 $1.04/小时                        | 生产级自治智能体系统                          |

> 💡 **成本提示：** 在开发和测试阶段，请使用 OpenAI 或 Anthropic API（无需 GPU）。只有在出于隐私或成本原因需要本地 LLM 推理时，才切换到 GPU 实例。参见 [GPU 比较指南](/guides/guides_v2-zh/ru-men-zhi-nan/gpu-comparison.md).

### 前提条件

* 带 SSH 访问的 Clore.ai 服务器
* Docker + Docker Compose（Clore.ai 预装）
* Git（预装）
* 4+ vCPU，8+ GB RAM（并发智能体建议 16 GB）
* OpenAI API 密钥 **或** 本地 LLM 端点（Ollama/vLLM）

***

## 快速开始

### 方法 1：Docker Compose（官方——推荐）

SuperAGI 的官方部署使用 Docker Compose 来管理所有服务。

**步骤 1：连接到你的 Clore.ai 服务器**

```bash
ssh root@<your-clore-server-ip> -p <ssh-port>
```

**步骤 2：克隆并配置**

```bash
git clone https://github.com/TransformerOptimus/SuperAGI.git
cd SuperAGI
cp config_template.yaml config.yaml
```

**步骤 3：编辑 `config.yaml`**

```bash
nano config.yaml
```

最低必需配置：

```yaml
# config.yaml
OPENAI_API_KEY: "sk-your-openai-key-here"

# 数据库（Docker Compose 保持默认即可）
POSTGRES_DB: "super_agi"
POSTGRES_USER: "super_agi"
POSTGRES_PASSWORD: "password"

# 向量数据库
VECTOR_STORE: "Redis"  # 或 "Pinecone"、"Qdrant"、"Weaviate"
REDIS_URL: "redis://super__agi-redis-1:6379/0"

# 应用设置
ENV: "PROD"
ALLOW_LISTS_CREATION: "true"

# 可选：限制访问
# AUTH_SECRET_KEY: "your-random-secret"
```

**步骤 4：启动技术栈**

```bash
docker compose up -d --build
```

构建过程会下载依赖并编译前端（首次运行约需 5–10 分钟）。

**步骤 5：监控启动**

```bash
# 观察所有服务启动
docker compose ps

# 查看日志
docker compose logs -f

# 等待后端日志中出现 "Application startup complete"
docker compose logs superagi-backend --tail 30
```

**步骤 6：访问仪表盘**

```
http://<your-clore-server-ip>:3000
```

API 可通过以下地址访问：

```
http://<your-clore-server-ip>:8001
```

API 文档：

```
http://<your-clore-server-ip>:8001/docs
```

***

### 方法 2：使用预构建镜像快速开始

如需使用预构建镜像加快启动（跳过构建步骤）：

```bash
git clone https://github.com/TransformerOptimus/SuperAGI.git
cd SuperAGI
cp config_template.yaml config.yaml

# 使用你的 API 密钥编辑配置
nano config.yaml

# 如果可用，请使用预构建镜像
docker compose -f docker-compose.yaml pull
docker compose up -d
```

***

### 方法 3：最小单模型设置

用于仅使用 OpenAI 进行测试的精简设置：

```bash
git clone https://github.com/TransformerOptimus/SuperAGI.git
cd SuperAGI

# 创建最小配置
cat > config.yaml << 'EOF'
OPENAI_API_KEY: "sk-your-key-here"
POSTGRES_DB: "super_agi"
POSTGRES_USER: "super_agi"
POSTGRES_PASSWORD: "superagi_password_123"
REDIS_URL: "redis://super__agi-redis-1:6379/0"
ENV: "PROD"
EOF

docker compose up -d --build

# 监控构建进度
docker compose logs superagi-frontend --tail 5 -f &
docker compose logs superagi-backend --tail 5 -f
```

***

## 配置

### `config.yaml` 参考

```yaml
# ============================================================
# LLM 提供方
# ============================================================
OPENAI_API_KEY: "sk-..."                    # OpenAI GPT 模型
ANTHROPIC_API_KEY: "sk-ant-..."            # Claude 模型

# 用于本地模型（Ollama 或 OpenAI 兼容 API）
# 在 UI 中设置：Settings → Models → Custom Model
OPENAI_API_BASE: "http://172.17.0.1:11434/v1"  # 同一主机上的 Ollama
OPENAI_MODEL: "llama3.1:8b"

# ============================================================
# 数据库
# ============================================================
POSTGRES_DB: "super_agi"
POSTGRES_USER: "super_agi"
POSTGRES_PASSWORD: "your-strong-password"

# ============================================================
# 向量数据库（智能体长期记忆）
# ============================================================
VECTOR_STORE: "Redis"       # Redis（默认，内置）
# 或使用外部：
# VECTOR_STORE: "Pinecone"
# PINECONE_API_KEY: "your-key"
# PINECONE_ENVIRONMENT: "us-east-1-aws"

# VECTOR_STORE: "Weaviate"
# WEAVIATE_URL: "http://weaviate:8080"

# ============================================================
# 工具 API 密钥（可选，适用于特定工具）
# ============================================================
GOOGLE_API_KEY: "your-google-key"
GOOGLE_CUSTOM_SEARCH_ENGINE_ID: "your-cx-id"
GITHUB_TOKEN: "ghp_your-token"
JIRA_EMAIL: "your@email.com"
JIRA_API_TOKEN: "your-jira-token"
JIRA_SERVER_URL: "https://your-org.atlassian.net"

# ============================================================
# 存储
# ============================================================
STORAGE_TYPE: "File"        # 本地文件存储
# STORAGE_TYPE: "S3"        # 兼容 S3（MinIO、AWS）
# BUCKET_NAME: "superagi"
# AWS_ACCESS_KEY_ID: "..."
# AWS_SECRET_ACCESS_KEY: "..."

# ============================================================
# 安全
# ============================================================
JWT_SECRET_KEY: "your-random-secret-key"
```

### 将 SuperAGI 连接到工具

工具可通过以下 GUI 进行配置： **Settings → Toolkit**。每个工具都可以按智能体启用/禁用。

**内置工具：**

| 工具         | 用途                        | 需要 API 密钥     |
| ---------- | ------------------------- | ------------- |
| Google 搜索  | 网页搜索                      | 是（Google API） |
| DuckDuckGo | 网页搜索                      | 否             |
| GitHub     | 代码仓库访问                    | 是（GitHub 令牌）  |
| 电子邮件       | 发送/读取电子邮件                 | 是（SMTP 配置）    |
| 代码编写器      | 编写并执行代码                   | 否             |
| 文件管理器      | 读取/写入本地文件                 | 否             |
| 浏览器        | 无头网页浏览                    | 否             |
| Jira       | 问题跟踪                      | 是             |
| Notion     | 知识库                       | 是             |
| 图像生成       | DALL-E 3、Stable Diffusion | 是（OpenAI 密钥）  |

### 创建你的第一个智能体

通过 GUI（Settings → Agents → Create Agent）：

1. **名称** —— 为你的智能体起一个有描述性的名称
2. **描述** —— 这个智能体的作用
3. **目标** —— 列出目标（每行一个）
4. **说明** —— 行为的系统提示词
5. **模型** —— 选择 LLM（GPT-4、Claude 或本地）
6. **工具** —— 启用相关工具
7. **最大迭代次数** —— 安全限制（通常为 10–50）

通过 REST API：

```bash
# 通过 API 创建智能体
curl -X POST "http://localhost:8001/v1/agent" \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "Research Agent",
    "description": "研究主题并撰写摘要",
    "goal": [
      "研究提供的主题",
      "撰写一份全面摘要",
      "将摘要保存到文件"
    ],
    "agent_type": "Task Queue",
    "constraints": [],
    "tools": ["DuckDuckGoSearch", "WriteFileTool", "ReadFileTool"],
    "exit_criterion": "无退出条件",
    "max_iterations": 25,
    "user_timezone": "UTC",
    "llm_model_config": {
      "model_name": "gpt-4o-mini",
      "temperature": 0.5,
      "max_new_tokens": 2000
    }
  }'
```

***

## GPU 加速

SuperAGI 支持通过任何兼容 OpenAI 的端点进行本地 LLM 推理，这使其非常适合 GPU 驱动的 Clore.ai 部署。

### 将 Ollama 设为智能体 LLM 后端

查看 [Ollama 指南](/guides/guides_v2-zh/yu-yan-mo-xing/ollama.md) 以获取完整的 Ollama 配置。与 SuperAGI 的集成：

**步骤 1：在同一台 Clore.ai 服务器上启动 Ollama**

```bash
docker run -d \\
  --name ollama \\
  --gpus all \\
  --restart unless-stopped \
  -p 11434:11434 \
  -v ollama_models:/root/.ollama \\
  ollama/ollama

# 拉取适合智能体使用的模型（需要较强推理能力）
docker exec ollama ollama pull llama3.1:8b        # 快速，推理能力好
docker exec ollama ollama pull mistral:7b-instruct  # 代码任务
docker exec ollama ollama pull deepseek-coder:6.7b # 重代码型智能体
```

**步骤 2：将 SuperAGI 配置为使用 Ollama**

在 `config.yaml`:

```yaml
# 指向 Ollama（运行在 Docker 主机上）
OPENAI_API_BASE: "http://172.17.0.1:11434/v1"
```

或者在 SuperAGI UI 中配置：

* **Settings → Models → Add Custom Model**
* 提供方：兼容 OpenAI
* 基础 URL： `http://172.17.0.1:11434/v1`
* API Key： `ollama` （任意字符串）
* 模型名称： `llama3.1:8b`

### 为高吞吐智能体设置 vLLM

适用于有大量并发智能体的生产部署（参见 [vLLM 指南](/guides/guides_v2-zh/yu-yan-mo-xing/vllm.md)):

```bash
# 在 GPU 服务器上启动 vLLM
docker run -d \\
  --name vllm \\
  --gpus all \\
  --restart unless-stopped \
  -p 8000:8000 \
  -v hf_cache:/root/.cache/huggingface \\
  -e HF_TOKEN=hf_your-token \\
  vllm/vllm-openai:latest \
  --model mistralai/Mistral-7B-Instruct-v0.3 \
  --served-model-name mistral-7b \\
  --max-model-len 8192 \\
  --enable-prefix-caching

# 在 config.yaml 中：
# OPENAI_API_BASE: "http://172.17.0.1:8000/v1"
```

### 智能体工作负载的 GPU 规格

| 使用场景  | 模型                  | GPU         | 显存    | 并发智能体      |
| ----- | ------------------- | ----------- | ----- | ---------- |
| 测试    | GPT-4o-mini（API）    | 无           | —     | 无限制（受速率限制） |
| 轻量智能体 | Llama 3.1 8B        | RTX 3090    | 8 GB  | 2–4        |
| 推理任务  | Mistral 7B Instruct | RTX 3090    | 6 GB  | 3–5        |
| 复杂智能体 | Llama 3.1 70B Q4    | 2× RTX 3090 | 48 GB | 1–2        |
| 生产环境  | Llama 3.1 70B FP16  | A100 80GB   | 80 GB | 3–6        |

***

## 提示与最佳实践

### 智能体设计

* **在目标上要具体** —— 像“做研究”这样的模糊目标会导致智能体循环。请使用“研究 X 并将 500 字摘要写入文件 output.txt。”
* **设置迭代限制** —— 始终设置 `max_iterations` （20–50）。无限制的智能体会迅速消耗 token。
* **使用任务队列模式** —— 对于多步骤流水线，“Task Queue” 智能体比 “Don't Limit” 模式更可靠。
* **先用便宜模型测试** —— 在使用昂贵模型之前，先用 GPT-4o-mini 或本地 7B 模型验证智能体逻辑。

### Clore.ai 上的成本管理

```bash
# 在 SuperAGI 仪表盘中实时监控 token 使用量
# Settings → Resources → Token Usage

# 在 config.yaml 中设置组织级限制
MAX_BUDGET_TOKENS: 100000  # 每个会话的软限制
```

由于 Clore.ai 按小时计费：

```bash
# 在停止实例之前保存智能体配置
docker compose exec superagi-backend \\
  python -c "import json; from superagi.models import Agent; ..."

# 备份 PostgreSQL 数据库
docker compose exec super__agi-db-1 \\
  pg_dump -U super_agi super_agi | gzip > superagi-db-$(date +%Y%m%d).sql.gz

# 将备份复制到服务器外部
scp -P <ssh-port> root@<server-ip>:~/SuperAGI/superagi-db-*.sql.gz ./
```

### 保护 SuperAGI 安全

```bash
# 在 config.yaml 中启用身份验证
AUTH_SECRET_KEY: "your-strong-random-secret"

# 将 API 限制为仅本地主机（使用 SSH 隧道）
# 修改 docker-compose.yml，移除外部端口绑定：
# ports:
#   - "127.0.0.1:8001:8001"  # API 仅限本地访问
#   - "127.0.0.1:3000:3000"  # 仅限本地 UI

# 然后通过 SSH 隧道访问：
# ssh -L 3000:localhost:3000 -L 8001:localhost:8001 root@<server-ip> -p <port>
```

### Clore.ai 会话之间的持久存储

```bash
# 创建完整备份脚本
cat > /root/backup-superagi.sh << 'EOF'
#!/bin/bash
cd ~/SuperAGI

# 备份数据库
docker compose exec -T super__agi-db-1 \\
  pg_dump -U super_agi super_agi | \\
  gzip > ~/backups/superagi-db-$(date +%Y%m%d-%H%M).sql.gz

# 备份配置和工作区
tar -czf ~/backups/superagi-files-$(date +%Y%m%d-%H%M).tar.gz \\
  config.yaml \\
  workspace/ \\
  .env 2>/dev/null || true

echo "备份完成：$(ls -lh ~/backups/ | tail -2)"
EOF

chmod +x /root/backup-superagi.sh
mkdir -p ~/backups
```

### 更新 SuperAGI

```bash
cd ~/SuperAGI

# 保存当前配置
cp config.yaml config.yaml.backup

# 拉取最新更改
git pull origin main

# 重新构建并重启
docker compose down
docker compose up -d --build

# 检查所有服务是否健康
docker compose ps
docker compose logs superagi-backend --tail 20
```

***

## 故障排查

### 构建失败时 `docker compose up --build`

```bash
# 详细检查构建日志
docker compose build superagi-backend --no-cache 2>&1 | tail -50

# 常见修复：释放磁盘空间
docker system prune -f
df -h  # 确保至少有 10 GB 可用空间

# 如果前端的 npm 构建失败
docker compose build superagi-frontend --no-cache

# 检查构建期间的 Node.js 内存
docker compose build superagi-frontend \\
  --build-arg NODE_OPTIONS="--max-old-space-size=4096"
```

### 后端在启动时崩溃

```bash
# 检查后端日志
docker compose logs superagi-backend --tail 50

# 常见原因：
# 1. config.yaml 语法无效
python3 -c "import yaml; yaml.safe_load(open('config.yaml'))" && echo "YAML 正常"

# 2. 数据库尚未就绪
docker compose restart superagi-backend  # 先等待数据库启动

# 3. 缺少 API 密钥
grep OPENAI_API_KEY config.yaml  # 确保已设置且不为空
```

### 前端未加载（端口 3000）

```bash
# 检查前端容器
docker compose ps superagi-frontend
docker compose logs superagi-frontend --tail 30

# 验证端口映射
ss -tlnp | grep 3000

# 检查前端是否可访问 API 后端
docker compose exec superagi-frontend \\
  curl -s http://superagi-backend:8001/health
```

### Agent 无限循环

```bash
# 在 SuperAGI UI 中查看 Agent 日志：
# 仪表板 → Agent → 查看日志

# 通过 API 强制停止正在运行的 Agent
curl -X POST "http://localhost:8001/v1/agent/<agent-id>/stop" \\
  -H "Content-Type: application/json"

# 或通过数据库停止所有 Agent
docker compose exec super__agi-db-1 \\
  psql -U super_agi -c "UPDATE agent_executions SET status='COMPLETED' WHERE status='RUNNING';"
```

### Redis 连接错误

```bash
# 检查 Redis 状态
docker compose ps super__agi-redis-1
docker compose logs super__agi-redis-1

# 测试 Redis 连接
docker compose exec superagi-backend \\
  python3 -c "import redis; r=redis.from_url('redis://super__agi-redis-1:6379/0'); print(r.ping())"

# 重启 Redis
docker compose restart super__agi-redis-1
```

### SuperAGI 容器无法访问 Ollama

```bash
# 查找 Docker 网桥 IP
docker network inspect bridge | grep Gateway

# 在后端容器中测试
docker compose exec superagi-backend \\
  curl -s http://172.17.0.1:11434/v1/models

# 如果使用主机网络
docker run -d --network host ...  # 与 docker compose 不太兼容

# 替代方案：将 Ollama 添加到同一 compose 网络
# 添加到 docker-compose.yml 的 services：
# ollama:
#   image: ollama/ollama
#   deploy:
#     resources:
#       reservations:
#         devices:
#           - driver: nvidia
#             count: all
#             capabilities: [gpu]
```

### 数据库连接池已耗尽

```bash
# 在 docker-compose.yml 中增加 PostgreSQL 最大连接数
# 在 db 服务下：
command: postgres -c max_connections=200

# 重启数据库
docker compose restart super__agi-db-1
docker compose restart superagi-backend
```

***

## 延伸阅读

* [SuperAGI 文档](https://superagi.com/docs) — 官方指南、API 参考
* [SuperAGI GitHub](https://github.com/TransformerOptimus/SuperAGI) — 源代码、问题、社区
* [在 Clore.ai 上运行 Ollama](/guides/guides_v2-zh/yu-yan-mo-xing/ollama.md) — Agent 的本地 LLM 后端
* [在 Clore.ai 上运行 vLLM](/guides/guides_v2-zh/yu-yan-mo-xing/vllm.md) — 面向并发 Agent 的高吞吐推理
* [GPU 比较指南](/guides/guides_v2-zh/ru-men-zhi-nan/gpu-comparison.md) — 选择合适的 Clore.ai 套餐
* [SuperAGI 工具市场](https://superagi.com/marketplace/) — 社区构建的 Agent 工具
* [SuperAGI Discord](https://discord.gg/dXbRe5BHJC) — 社区支持与讨论
* [FastAPI 文档（SuperAGI API）](http://localhost:8001/docs) — 你实例上的交互式 API 文档


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.clore.ai/guides/guides_v2-zh/ai-ping-tai-yu-zhi-neng-ti/superagi.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.