STEP1. 概要流程 #

1. 啟用 WSL 2 與必要的 Windows 功能

2. 安裝 Docker Desktop（WSL 2 後端）

3. 複製 AgentSeek 儲存庫並準備 Python 虛擬環境 (venv)

4. 使用 Docker Compose 啟動「前端 + Redis + SearxNG」

5. 手動確認 FastAPI 後端 → 使用 NSSM 轉為 Windows 服務

6. 將 BACKEND_URL 變更為 host.docker.internal:8000 以與前端連動

7. 重新啟動測試與營運確認

STEP2. 前提環境檢查 #

建議：在具有系統管理員權限的 PowerShell 中進行所有作業，可避免權限錯誤。

STEP3. 啟用 WSL 2 與 Windows 功能 #

wsl --install -d Ubuntu          # 預設安裝 22.04
# 若出現錯誤，請個別執行以下指令：
# dism /online /enable-feature ...
# wsl --update
# wsl --set-default-version 2

完成後重新啟動電腦，並使用 wsl -l -v 確認 Ubuntu 以 Version 2 運作。

STEP4. 安裝 Docker Desktop #

winget install -e --id Docker.DockerDesktop

初次啟動時的設定 #

• Use the WSL 2 based engine → ON

• Add Docker CLI to the PATH → ON

• Start Docker Desktop when you log in → ON (General 標籤)

當工作列的鯨魚圖示顯示_綠色標記_並穩定時即表示完成。

STEP5. 取得原始碼與 Python 虛擬環境 #

cd C:Dev               # 任意的工作目錄
git clone https://github.com/AgenticSeek/agenticSeek.git
cd agenticSeek
python -m venv .venv
..venvScriptsActivate.ps1
pip install -r requirements.txt

編輯 config.ini，並指定 GPUStack 等後端 LLM 的端點：

[PROVIDER]
provider_name = gpustack
provider_server_address = http://<GPUStack_IP>:<port>/v1

[BROWSER]
headless_browser = True  ; 若要隱藏瀏覽器

STEP6. 使用 Docker Compose 啟動前端 #

修改 docker-compose.yml 的 frontend.environment，使其參照主機的 FastAPI。

environment:
  - NODE_ENV=development
  - CHOKIDAR_USEPOLLING=true
  - BACKEND_URL=http://host.docker.internal:8000
  - VITE_BACKEND_URL=http://host.docker.internal:8000

# 套用變更
docker compose down
docker compose up -d --build   # 初次執行建議使用 --build

狀態確認：

docker compose ps

當 frontend | Up、redis | Up、searxng | Up 時即表示準備完成。

STEP7. 手動啟動 FastAPI 後端測試 #

cd C:AgentSeekagenticSeek
..venvScriptsActivate.ps1
python api.py --host 0.0.0.0 --port 8000

• 在瀏覽器中開啟 http://localhost:8000/docs 即表示成功。

• 按 Ctrl + C 停止。

STEP8. 使用 NSSM 將後端設為 Windows 服務 #

8-1 下載 NSSM #

從 https://nssm.cc/download 下載 nssm-2.24.zip 並解壓縮：例如 C:Toolsnssmnssm.exe

8-2 註冊服務(以管理員身分執行 PowerShell) #

& "C:Toolsnssmnssm.exe" install AgentSeekBackend ^
  "C:AgentSeekagenticSeek.venvScriptspython.exe" ^
  "api.py --host 0.0.0.0 --port 8000" ^
  -d "C:AgentSeekagenticSeek"

額外設定 #

• I/O 分頁

  • Output: C:AgentSeekagenticSeek.logsbackend.log

  • Error: C:AgentSeekagenticSeek.logsbackend-err.log

• Service 分頁

  • Start type: Automatic (Delayed Start)

Start-Service AgentSeekBackend
Get-Service AgentSeekBackend   # Status: Running

STEP9. 運作驗證 #

1. 瀏覽器 → http://localhost:3000 → 右上顯示 Connected

2. Swagger UI → http://localhost:8000/docs 可開啟

3. 重新啟動測試後若①②仍維持，表示自動啟動設定已完成

STEP10. 代理使用技巧 #

• GUI 會自動路由分配代理

• 指定特定代理

  • @FileAgent zip *.csv into files.zip

  • 也可使用 JSON 指令格式: @FileAgent {"action":"zip","pattern":"*.csv"}

• 若要 100% 固定使用，請使用 CLI:

  python cli.py --agent FileAgent "zip *.csv"

STEP11. 疑難排解速查表 #

STEP12. 參考連結 #

• Docker Desktop Documentation https://docs.docker.com/desktop/windows/

• NSSM – the Non‑Sucking Service Manager https://nssm.cc/

• AgentSeek GitHub (開發分支) https://github.com/AgenticSeek/agenticSeek

以上即完成在 Windows 11 上穩定營運 AgentSeek WebGUI 的設定步驟。