如何使用 Docker 自托管 AgentGPT 并接入本地与私有化 LLM 端点

在企业内网或本地硬件环境中自托管 AgentGPT，可以让开发与安全团队在不泄露内部目标、商业机密或敏感数据的前提下，完整运行自主智能体（Autonomous Agents）任务流。由于自主智能体在执行任务时需要递归拆解子任务、评估执行效果并反复调用模型，自建本地或私有化大模型推理端点，还能彻底避免公有云 API 循环调用产生的高昂 Token 账单与频次限流。

AgentGPT（由 Reworkd 开源）是一套基于 Web 的自主智能体平台，技术架构由 Next.js 前端、FastAPI 平台后端以及 MySQL 数据库组成。平台默认对接 OpenAI 公共服务，但通过配置 Docker 容器网络、环境变量以及兼容 OpenAI 接口规范的本地推理引擎（如 Ollama、LocalAI 或 vLLM），即可构建一套完全离线、合规且自主可控的智能体工作流。

架构拆解与容器网络通信陷阱

自托管 AgentGPT 依赖 Docker Compose 编排三个核心容器服务：

1. 前端服务 (next)：监听 3000 端口，提供可视化智能体创建与实时任务追踪面板。
2. 后端平台 (platform)：监听 8000 端口，基于 FastAPI 运行智能体决策环路、任务队列调度与大模型接口交互。
3. 数据库 (db)：监听 3306 端口，基于 MySQL 存储智能体历史运行记录、子任务状态与系统配置。

+-------------------------------------------------------------------------+
| Docker 内部网络 (agentgpt-network)                                      |
|                                                                         |
|  [ 前端: Next.js ] <---> [ 后端: FastAPI Platform ] <---> [ 数据库 ]   |
|       (:3000)                        (:8000)                   (:3306)  |
+------------------------------------------|------------------------------+
                                           | (REWORKD_PLATFORM_OPENAI_API_BASE)
                                           v
                     +--------------------------------------------+
                     | 宿主机 / 内网私有化算力节点                 |
                     | host.docker.internal:11434/v1              |
                     | [ Ollama / vLLM / LocalAI 私有端点 ]       |
                     +--------------------------------------------+

容器访问宿主机的网络边界

配置本地模型时最常遇到的网络报错，是将 API 地址填写为 http://localhost:11434 或 http://127.0.0.1:11434。在 Docker 容器内部，localhost 指向的是容器自身的隔离网络空间，而非宿主机上运行的推理引擎。

正确跨越网络边界的方式如下：

• macOS 与 Windows（Docker Desktop）：直接使用 http://host.docker.internal:11434/v1。
• Linux 原生环境：必须在 docker-compose.yml 的 platform 后端服务中添加 extra_hosts: ["host.docker.internal:host-gateway"]，使容器能够通过宿主机网关解析该域名。
• 同 Compose 网络部署：若将 Ollama 或 LocalAI 也放入同个 Compose 编排中，直接使用服务名称（例如 http://ollama:11434/v1）。

第一步：准备本地或私有化 LLM 服务

本地推理框架必须暴露符合 OpenAI 规范的 HTTP REST API（核心需支持 /v1/chat/completions 与 /v1/models）。

方案 A：使用 Ollama（适合本地工作站与开发者开发环境）

启动 Ollama 并绑定到全网络接口，确保 Docker 容器能正常建立连接：

# 在 Linux 下配置 systemd 或直接通过环境变量启动
OLLAMA_HOST=0.0.0.0:11434 ollama serve

下载具备较强逻辑推理与结构化输出能力的高性能开源模型：

ollama pull qwen2.5:14b
# 或
ollama pull llama3.1:8b

通过 cURL 验证兼容端点是否就绪：

curl http://localhost:11434/v1/models

方案 B：使用 vLLM（适合企业级私有算力与高并发生产环境）

在具备 GPU 算力的私有服务器上启动 vLLM 兼容服务：

python3 -m vllm.entrypoints.openai.api_server \
  --model meta-llama/Llama-3.1-8B-Instruct \
  --host 0.0.0.0 \
  --port 8000

第二步：拉取 AgentGPT 并配置环境变量

克隆官方代码仓库：

git clone https://github.com/reworkd/AgentGPT.git
cd AgentGPT

复制配置文件模版：

cp .env.example .env

.env 关键配置项详解

编辑项目根目录下的 .env（若手动构建服务，需同时同步至 platform/.env）：

# ----------------------------------------
# 大模型接口与端点配置
# ----------------------------------------
# 指向宿主机上的本地推理端点（通过 host.docker.internal 解析）
# 注意：末尾绝不能带斜杠（写 /v1，切勿写 /v1/）
REWORKD_PLATFORM_OPENAI_API_BASE=http://host.docker.internal:11434/v1

# OpenAI SDK 校验机制要求 API Key 不能为空字符串
# 本地模型通常忽略此字段，填入任意占位字符串即可
OPENAI_API_KEY=local-secret-key

# ----------------------------------------
# 数据库凭据
# ----------------------------------------
DATABASE_URL=mysql://root:password@db:3306/agentgpt
MYSQL_ROOT_PASSWORD=password
MYSQL_DATABASE=agentgpt

# ----------------------------------------
# 认证与安全令牌
# ----------------------------------------
NEXTAUTH_SECRET=generate-a-secure-random-32-byte-hex-key
NEXTAUTH_URL=http://localhost:3000

语法要点：REWORKD_PLATFORM_OPENAI_API_BASE 的路径末尾切勿附加 /chat/completions 或多余斜杠 /。AgentGPT 内部客户端会自动补全请求路径，额外的斜杠会导致服务拼接出 //chat/completions，进而引发 HTTP 404 错误。

第三步：针对 Linux 调整 docker-compose.yml

针对 Linux 宿主机，在 docker-compose.yml 中为 platform 服务补充网关映射：

services:
  platform:
    build:
      context: ./platform
      dockerfile: Dockerfile
    environment:
      - REWORKD_PLATFORM_OPENAI_API_BASE=http://host.docker.internal:11434/v1
      - OPENAI_API_KEY=local-secret-key
      - DATABASE_URL=mysql://root:password@db:3306/agentgpt
    ports:
      - "8000:8000"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    depends_on:
      - db

  frontend:
    build:
      context: ./next
      dockerfile: Dockerfile
    ports:
      - "3000:3000"
    environment:
      - NEXTAUTH_URL=http://localhost:3000
      - NEXTAUTH_SECRET=generate-a-secure-random-32-byte-hex-key
    depends_on:
      - platform

  db:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: agentgpt
    ports:
      - "3306:3306"
    volumes:
      - db_data:/var/lib/mysql

volumes:
  db_data:

第四步：构建并启动容器集群

使用 Docker Compose 启动容器集群：

docker compose up -d --build

查看初始化日志，确认后端服务与数据库连接建立完毕：

docker compose logs -f platform

所有服务就绪后，在浏览器中访问 http://localhost:3000 进入 AgentGPT 控制面板。

第五步：在 Web 界面中配置与测试智能体工作流

1. 进入设置界面：点击 AgentGPT 左下角导航栏的齿轮图标 Settings。
2. 选择模型名称：在模型配置项中填入本地推理引擎正在运行的模型标识（例如 qwen2.5:14b 或 llama3.1:8b）。
3. 调整执行参数：
   • Temperature（采样温度）：建议调低至 0.2 – 0.4。自主智能体的核心在于任务分解与严格的 JSON 格式解析，过高的温度容易引起输出语法破损或子任务无限循环。
   • Loop Cap（执行轮数上限）：初始测试建议设置为 5 到 10 轮，防止硬件算力排队过长导致任务卡死。
4. 发起测试任务：
   • Agent Name：Local-Architecture-Analyst
   • Goal：分析企业内网自建 AI 智能体平台的网络瓶颈，并按优先级列出三项具体的优化措施。
   • 点击 Deploy Agent。
5. 观测执行过程：观察控制台动态拆解目标、生成并分派子任务、逐项调用本地模型推理，并最终输出综合归纳报告。

避坑指南与模型选型要点

1. 本地模型能力门槛

自主智能体对底层模型的综合能力要求远高于日常对话场景：

• 必须严格遵守系统指令并稳定输出合规的 JSON 数据结构。
• 具备准确评估任务完成状态的能力，避免陷入原地打转的死循环。

小于 7B 参数量的微型模型或未经指令微调的模型，极易因格式解析失败而中断任务。建议采用的基线配置：

• 最低实用门槛：Llama-3.1-8B-Instruct 或 Qwen-2.5-7B-Instruct。
• 推荐生产基线：Qwen-2.5-14B/32B 或 Llama-3.1-70B（支持在多卡或大显存工作站进行量化部署）。

2. 上下文长度截断问题

随着任务递归执行，智能体维护的上下文历史会迅速膨胀。务必在本地推理引擎中调高上下文窗口大小：

• 在 Ollama 中可编写自定义 Modelfile，设置 PARAMETER num_ctx 16384，防止长链路执行时上下文被静默截断。

3. 开源仓库维护状态说明

需要注意，GitHub 上的 reworkd/AgentGPT 仓库已于 2026 年 1 月归档为只读状态。该工程架构成熟，适合作为内部智能体系统自建与二开的参考实现；但对于长期生产使用，工程团队应当固定底层依赖包版本，自建内部 Docker 基础镜像并维护私有凭据管理策略。

参考资料

• GitHub - reworkd/AgentGPT: 🤖 Assemble, configure, and deploy autonomous AI Agents in your browser.
• Docker Compose | Docker Docs
• GitHub - ollama/ollama: Get up and running with Kimi, GLM, MiniMax, DeepSeek, gpt-oss, Qwen, Gemma and other models.