如何使用 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）亦以容器方式運作於同一個 Compose 專案內，可直接使用服務名稱（如 http://ollama:11434/v1）。

步驟一：準備本地或私有化 LLM 服務

本地推論引擎必須提供相容於 OpenAI 規範的 HTTP REST 端點（核心需支援 /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 叢集的企業級高並發環境）

於 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 並設定環境變數

複製官方 GitHub 儲存庫：

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

建立環境變數設定檔：

cp .env.example .env

.env 核心變數配置

編輯專案根目錄下的 .env（若採個別目錄手動建置，亦須同步更新 platform/.env）：

# ----------------------------------------
# LLM 端點配置
# ----------------------------------------
# 指向實體主機的本地推論服務（透過 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 驗證密鑰
# ----------------------------------------
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

檢視後端日誌，確認與 MySQL 資料庫成功建立連線：

docker compose logs -f platform

容器皆正常運作後，開啟瀏覽器造訪 http://localhost:3000 進入控制介面。

步驟五：在網頁介面配置並執行智能體任務

1. 開啟設定視窗：點選 AgentGPT 左下角導覽列的齒輪圖示 Settings。
2. 輸入模型標籤：填入本地推論引擎中部署的模型名稱（例如 qwen2.5:14b 或 llama3.1:8b）。
3. 調整執行參數：
   • Temperature（取樣溫度）：建議設定在 0.2 至 0.4 之間。自主智能體依賴穩定的邏輯規劃與嚴謹的 JSON 結構輸出，溫度過高容易造成語法解析失敗或產生無窮遞迴。
   • Max Loops（執行迴圈上限）：初期測試建議設定為 5 到 10 輪，避免本地運算排隊過久。
4. 派發執行任務：
   • Agent Name：Local-Architecture-Analyst
   • Goal：分析企業內部自建 AI 智能體平台面臨的網路瓶頸，並依優先順序提出三項具體的改善措施。
   • 點選 Deploy Agent。
5. 觀察執行流程：即時觀察智能體如何將宏觀目標拆解為微觀子任務、逐一呼叫本地推論引擎執行，並產出最終彙整報告。

關鍵實務考量與模型挑選要點

1. 本地模型能力門檻

自主智能體對基礎模型的能力要求顯著高於一般的交談對話機器人：

• 模型必須能嚴格遵從複雜的 System Prompt 指令並輸出合乎規格的 JSON 資料結構。
• 具備清晰的邏輯判斷力，能評估當前任務是否已達成，而非無止境產出重複步驟。

參數量低於 7B 或未針對指令微調的模型，常因輸出格式不符而中斷工作流。推薦採用的基線模型：

• 最低實用標準：Llama-3.1-8B-Instruct 或 Qwen-2.5-7B-Instruct。
• 最佳生產基線：Qwen-2.5-14B/32B 或 Llama-3.1-70B（可於多卡工作站進行量化部署）。

2. 上下文長度截斷防範

隨著多輪任務持續執行，智能體累積的對話歷史將迅速增加。請務必在本地推論引擎中加大 Context Window：

• 以 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.