iT邦幫忙

2026 iThome 鐵人賽
DAY 0
0
AI 自動化

30天，利用 n8n Agents 打造一位 AI 同事系列 第 2 篇

Day 2：n8n Agents 自架教學，用 Docker 準備 AI Agent 練習環境

18th鐵人賽
53 瀏覽

  • 分享至 

  • xImage
    •  

準備開始學 Agents，打開 n8n，卻連 Agents 分頁都找不到。
新人還沒報到，辦公室先失蹤了。

這是我遇到的真實情況：在 n8n 官方 Cloud 裡找了兩次，仍未看到 Agents。帳號的開放狀態可能已經改變，你跟做時先看自己的畫面。

回頭查官方公告，這個畫面符合當時分批開放的情況。既然接下來 30 天每天都要實際操作，我不想把進度押在「不知道哪天會出現」上，所以決定先自架一套 n8n！

今天的任務是先準備環境：本文截圖使用 n8n 2.35.3，走的是附帶 AI Assistant 與程式執行沙盒的完整設定路線；手動建立 Agent 並不一定需要這些附加服務。

做完後，瀏覽器裡會出現 Agents 頁面，也能完成 AI Assistant 的初始設定。

如果你的 n8n Cloud 已經看得到 Agents，可以直接跳到 Day 3。
下面的 Docker 指令只適用於 self-hosted 環境，Cloud 沒有容器讓你執行。

先選手動建立，還是 Assistant 輔助建立

截至 2026-09-16，官方列出兩條自架路線：只啟用 agents 可手動設定模型、規則和工具；需要 Assistant 輔助建置才再啟用 instance-ai。本文歷史畫面裡的 Assistant 設定，並不是所有 Agent 的必要前置，兩條路線的差異可參考官方自架說明。

想先學 Agents 核心，可以把下面內容存成 compose.manual.yaml，這份手動版設定只會啟動 n8n：

# 補充手動 Agents 路線；沿用文章版本，非正式部署設定。
name: n8n-ironman-manual
services:
  n8n:
    image: n8nio/n8n:2.35.3
    ports:
      - "127.0.0.1:5684:5678"
    environment:
      N8N_ENABLED_MODULES: agents
      GENERIC_TIMEZONE: Asia/Taipei
      TZ: Asia/Taipei
    volumes:
      - n8n_manual_data:/home/node/.n8n
volumes:
  n8n_manual_data:

等下確認 Docker Desktop 已啟動後，在這個檔案所在的獨立資料夾執行：

docker compose -f compose.manual.yaml up -d

再開 http://localhost:5684，依下方「建立本機管理者帳號」完成首次設定。看到 Agents 分頁後，手動版今天就準備好了；不用再做 Assistant 和沙盒那一段。這份補充檔依官方手動路線整理，已做設定檢查，尚未重拍整套 UI。

本文下面的四服務截圖屬於 Assistant 版。兩條路線選一條，接下來沿用所選路線的資料 volume；若你已完成原本的環境，不必重建。

開始前要準備什麼？

這篇需要：

  1. 已安裝並啟動 Docker Desktop
  2. 一個模型可以讓 Agent 使用

模型可以接 OpenAI、Anthropic，也可以像我一樣用本機 Ollama。我這次選 Ollama 的 qwen3.5:9b，這樣之後反覆測試時不會一直計算 API 費用。

先在終端機輸入：

docker compose version

有看到 Docker Compose version 和版本號再繼續。如果顯示找不到指令，先回頭確認 Docker Desktop 是否真的啟動。

如果你選 Assistant 版，先把文末「完整設定檔」的兩段內容各自存成以下檔名，保留 YAML 的縮排：

  • compose.yaml
  • .env.example

手動版只需要前面的 compose.manual.yaml，不用建立這兩個檔案。以下直到四個完成條件，都在說明 Assistant 版。

把它們放在同一個新資料夾裡，再在該資料夾執行：

cp .env.example .env

compose.yaml 讀取的是 .env，所以要先把 .env.example 複製成這個檔名，後面的 sandbox API key 才會被帶進容器。

如果要和我一樣使用 Ollama，還要先安裝並啟動 Ollama，再下載今天指定的模型：

ollama pull qwen3.5:9b
ollama list

ollama list 裡看得到 qwen3.5:9b 才繼續。macOS 可以直接開啟 Ollama App；若你用 ollama serve 啟動，請另外保留那個終端視窗。已經決定使用 OpenAI 或 Anthropic 的讀者可以跳過這兩行，稍後改填自己的 provider 與 credential。

為什麼不是只啟動一個 n8n 容器？

我當時在 2.35.3 的建置入口按 Create agent，畫面帶到 AI Assistant，於是把這條路線的模型和程式執行沙盒一起設好。這是下面四服務配置的由來；現在要手動建立的讀者可用前面的精簡路線。

所以今天的 compose.yaml 會啟動四個服務：

服務 它在做什麼
n8n 我們實際操作的 n8n
sandbox-certs 第一次啟動時建立沙盒通訊憑證，完成後會正常退出
sandbox-api 接收 n8n 的程式執行請求
sandbox-runner-1 把 AI 產生的程式放進隔離容器執行

最重要的設定是：

N8N_ENABLED_MODULES: agents,instance-ai
N8N_INSTANCE_AI_SANDBOX_ENABLED: "true"
N8N_INSTANCE_AI_SANDBOX_API_URL: http://sandbox-api:8080

agents 啟用 Agents；instance-ai 啟用輔助建置的 AI Assistant。這裡的沙盒供 Assistant 執行程式，不等於每位 Agent 都已取得程式執行工具。原生 Knowledge 的自架需求也要另外確認，不能把這份 n8n Sandbox 配置當成已完成 Knowledge 設定。

這份 compose 讓 sandbox runner 使用 Docker 的 privileged 模式，只適合本機練習。正式環境要另外評估隔離方式，不要直接把今天的設定接上公司正式資料。

啟動整套環境

在剛才的資料夾執行：

docker compose --env-file .env up -d

第一次會下載數個映像檔，等下載和啟動完成後，再輸入：

docker compose ps -a

這裡加上 -a，才會連已退出的服務一起列出。n8n、sandbox-api 和 sandbox-runner-1 應該是 Up；sandbox-certs 顯示 Exited (0) 是正常的，因為它只負責產生一次憑證。

接著打開 http://localhost:5680/healthz：

self-hosted n8n 的 healthz 回傳 status ok

看到 {"status":"ok"} 只代表 n8n 活著，沙盒的狀態還要用下面的指令確認：

docker compose exec n8n wget -qO- http://sandbox-api:8080/healthz

預期也會得到：

{"status":"ok"}

這個指令只有 self-hosted 才能用。n8n Cloud 的沙盒由官方管理，不需要、也不能從 Cloud 網頁執行這段容器檢查。

建立本機管理者帳號

Assistant 版打開 http://localhost:5680；手動版則用 http://localhost:5684。第一次進入會看到 Set up owner account：

建立 self-hosted n8n 的 owner account

填入 Email、名字、姓氏和密碼，再按 Next。我這次使用的測試帳號是 ironman-day@example.test，密碼只放在自己的密碼管理器，不寫進文章或設定檔。

這個 Owner 帳號只需要建立一次，Day 3 到 Day 30 都會沿用同一個帳號和同一個資料 volume：Assistant 版是 n8n_data，手動版是 n8n_manual_data。保留 Compose 的 project name，讓 Data Tables、Agent、Sessions 與 Workflow 一天一天累積；不是每天建立一個新帳號。

完成後進入 Overview → Agents：

self-hosted n8n 已出現 Agents Preview

看到空白的 Agents 清單後，手動版就可以先停在這裡，等 Day 4 再到 Agent Builder 設定模型；Assistant 版則繼續下面的初始設定。

設定模型與 n8n Sandbox

以下沿用作者 2.35.3 的 Assistant 路線：按 Create agent 後，當時的畫面要求先設定 AI Assistant。手動路線則直接在 Agent Builder 設定模型。

模型選擇 Self-hosted / OpenAI-compatible，填入：

Base URL: http://host.docker.internal:11434/v1
API key: ollama
Model: qwen3.5:9b

這組值以 Docker Desktop 連接主機上的 Ollama 為前提，而且要先下載 qwen3.5:9b。host.docker.internal 指向主機，不能改成容器自己的 localhost。如果你用 OpenAI 或 Anthropic，就在這裡改選自己的 provider 和 credential，不必照抄 Ollama 的網址。

Code sandbox 選 n8n Sandbox：

Service URL: http://sandbox-api:8080
API key: ironman-local-sandbox-api-key

API key 必須和 .env 裡的 SANDBOX_API_KEYS 相同。Web search 今天先選 Disabled，因為前半段只會讀我們自己準備的資料。

設定完成後，畫面會列出模型、Code sandbox 和 Web search：

AI Assistant 已接上本機模型與 n8n Sandbox

這一篇留下的可見證據是 n8n 與 sandbox API 的 health check，以及 AI Assistant 畫面已保存模型和 n8n Sandbox 設定。status: ok 只能證明服務有回應，不能單靠它宣稱已經成功執行一段 sandbox 程式；若你要把這套環境用在正式工作，還要另外跑一次實際的程式執行測試並保存 log。

依照你選的路線，確認今天可以收工

今天先停在空白的 Agents 清單，不建立 Agent。

手動版只要確認 http://localhost:5684/healthz 回傳 status: ok，並且登入後看得到 Agents 分頁，就完成今天的環境準備。模型設定留到 Day 4。

Assistant 版則核對下面四個結果：

  1. http://localhost:5680/healthz 回傳 status: ok
  2. sandbox API 也回傳 status: ok
  3. Overview 裡出現 Agents Preview
  4. AI Assistant 顯示模型與 n8n Sandbox 都已設定

今天還沒有建立 Workflow，留下來的產物就是實際跑過的 compose.yaml 和 .env.example。

明天先建立五張 Data Tables，讓這位還沒上班的 AI 同事有地方讀資料、放草稿，也有地方留下考試成績。

分清三個執行位置，排錯才不會繞圈

瀏覽器、n8n container（容器）和模型服務位在三個不同的位置，可以想成同一間公司的三張桌子：各自說「我這裡」時，指的地方並不一樣。瀏覽器能開 n8n，只證明第一段連線；n8n 還必須從自己的執行位置連到模型。localhost 在 container 裡指向 container 自己，所以不要把瀏覽器成功的 URL 直接當成模型 Base URL。

跟做時記下 n8n 版本、模型名稱、Base URL、主機 port 和 volume 名稱。本文原 compose 預設 5680，歷史截圖使用 5690，補充手動版使用 5684；後面看到 5690 時要換成自己的值。模型標籤和 sandbox 的 latest 都可能移動，重跑結果要連同映像版本／模型 digest 記錄，不能只寫「和作者同一個模型」。

完整設定檔：Assistant 版

下面兩段就是本文四服務路線的完整設定，可以直接各自存成指定檔名，再回到「開始前要準備什麼？」複製 .env 並啟動。

這裡固定使用本文的 n8n 2.35.3，sandbox 映像沿用原設定的 latest。AI Assistant 的設定名稱可能隨版本變動；若改用新版 n8n，請對照 官方 Assistant 設定說明。官方目前使用 N8N_SANDBOX_SERVICE_URL 與 N8N_SANDBOX_SERVICE_API_KEY；本文仍保留原設定，並在 UI 明確填入 sandbox URL 與 key，不把它當成所有版本都適用的範本。

檔案一：compose.yaml

name: n8n-ironman

services:
  sandbox-certs:
    image: ghcr.io/n8n-io/n8n-sandbox-service-api:latest
    user: "0:0"
    entrypoint: ["sh", "-c"]
    command:
      - >
        bootstrap-mtls.sh --out-dir /tls --api-san sandbox-api
        --control-san-prefix sandbox-runner &&
        chown -R sandbox-api:sandbox-api /tls/api
    environment:
      NUM_RUNNERS: "1"
    volumes:
      - sandbox_tls:/tls

  sandbox-api:
    image: ghcr.io/n8n-io/n8n-sandbox-service-api:latest
    restart: unless-stopped
    depends_on:
      sandbox-certs:
        condition: service_completed_successfully
    environment:
      SANDBOX_API_KEYS: ${SANDBOX_API_KEYS}
      SANDBOX_API_RUNNER_REGISTRATION_TOKEN: ${SANDBOX_API_RUNNER_REGISTRATION_TOKEN}
      SANDBOX_API_RUNNER_API_KEY: ${SANDBOX_API_RUNNER_API_KEY}
      SANDBOX_API_GRPC_TLS_CERT_FILE: /tls/api/grpc-server.crt
      SANDBOX_API_GRPC_TLS_KEY_FILE: /tls/api/grpc-server.key
      SANDBOX_API_GRPC_TLS_CLIENT_CA_FILE: /tls/api/ca.crt
      SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_CA_FILE: /tls/api/ca.crt
      SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_CERT_FILE: /tls/api/control-grpc-api-client.crt
      SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_KEY_FILE: /tls/api/control-grpc-api-client.key
      SANDBOX_API_RUNNER_CONTROL_GRPC_TLS_SERVER_NAME: sandbox-runner-1
    volumes:
      - sandbox_tls:/tls:ro
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:8080/healthz"]
      interval: 5s
      timeout: 3s
      retries: 12
      start_period: 10s

  sandbox-runner-1:
    image: ghcr.io/n8n-io/n8n-sandbox-service-runner-dind:latest
    privileged: true
    restart: unless-stopped
    depends_on:
      sandbox-api:
        condition: service_healthy
    environment:
      SANDBOX_RUNNER_API_KEYS: ${SANDBOX_API_RUNNER_API_KEY}
      SANDBOX_RUNNER_REGISTRATION_TOKEN: ${SANDBOX_API_RUNNER_REGISTRATION_TOKEN}
      SANDBOX_RUNNER_API_GRPC_ADDR: sandbox-api:9090
      SANDBOX_RUNNER_HTTP_BASE_URL: http://sandbox-runner-1:8080
      SANDBOX_RUNNER_CONTROL_GRPC_LISTEN_ADDR: ":9091"
      SANDBOX_RUNNER_CONTROL_GRPC_ADVERTISE_ADDR: sandbox-runner-1:9091
      SANDBOX_RUNNER_ID: runner-1
      SANDBOX_RUNNER_DOCKER_SANDBOX_IMAGE: ghcr.io/n8n-io/n8n-sandbox-service-sandbox:latest
      SANDBOX_RUNNER_REGISTRATION_GRPC_CA_FILE: /tls/runner/ca.crt
      SANDBOX_RUNNER_REGISTRATION_GRPC_CERT_FILE: /tls/runner/grpc-client.crt
      SANDBOX_RUNNER_REGISTRATION_GRPC_KEY_FILE: /tls/runner/grpc-client.key
      SANDBOX_RUNNER_REGISTRATION_GRPC_SERVER_NAME: sandbox-api
      SANDBOX_RUNNER_CONTROL_GRPC_TLS_CERT_FILE: /tls/runner/control-grpc-server.crt
      SANDBOX_RUNNER_CONTROL_GRPC_TLS_KEY_FILE: /tls/runner/control-grpc-server.key
      SANDBOX_RUNNER_CONTROL_GRPC_TLS_CLIENT_CA_FILE: /tls/runner/ca.crt
    volumes:
      - sandbox_tls:/tls:ro

  n8n:
    image: n8nio/n8n:2.35.3
    restart: unless-stopped
    depends_on:
      sandbox-api:
        condition: service_healthy
    ports:
      - "127.0.0.1:${HOST_PORT:-5680}:5678"
    environment:
      N8N_ENABLED_MODULES: agents,instance-ai
      N8N_INSTANCE_AI_SANDBOX_ENABLED: "true"
      N8N_INSTANCE_AI_SANDBOX_PROVIDER: n8n-sandbox
      N8N_INSTANCE_AI_SANDBOX_IMAGE: ghcr.io/n8n-io/n8n-sandbox-service-sandbox:latest
      N8N_INSTANCE_AI_SANDBOX_API_URL: http://sandbox-api:8080
      N8N_INSTANCE_AI_SANDBOX_API_KEY: ${N8N_INSTANCE_AI_SANDBOX_API_KEY}
      N8N_DIAGNOSTICS_ENABLED: "false"
      N8N_PERSONALIZATION_ENABLED: "false"
      N8N_SECURE_COOKIE: "false"
      N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS: "true"
      N8N_EDITOR_BASE_URL: "http://localhost:${HOST_PORT:-5680}"
      WEBHOOK_URL: "http://localhost:${HOST_PORT:-5680}/"
      GENERIC_TIMEZONE: Asia/Taipei
      TZ: Asia/Taipei
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  n8n_data:
  sandbox_tls:

檔案二：.env.example

以下三組 key/token 都是公開的本機練習示例，請勿沿用到正式環境。N8N_INSTANCE_AI_SANDBOX_API_KEY 與稍後 UI 填入的 key，要和 SANDBOX_API_KEYS 一致。

# 只用於本機練習。正式環境請換成各自產生的長隨機值。
SANDBOX_API_KEYS=ironman-local-sandbox-api-key
SANDBOX_API_RUNNER_REGISTRATION_TOKEN=ironman-local-registration-token
SANDBOX_API_RUNNER_API_KEY=ironman-local-runner-key

# 必須與 SANDBOX_API_KEYS 的其中一個值相同。
N8N_INSTANCE_AI_SANDBOX_API_KEY=ironman-local-sandbox-api-key

上一篇
Day 1：什麼是 n8n Agents？今年我想做一位真的幫得上忙的 AI 同事
下一篇
Day 3：n8n Data Tables 教學，先替 AI 同事準備五本工作簿
系列文
30天，利用 n8n Agents 打造一位 AI 同事 共 6 篇
  1. 2
    Day 2：n8n Agents 自架教學，用 Docker 準備 AI Agent 練習環境
  2. 3
    Day 3：n8n Data Tables 教學，先替 AI 同事準備五本工作簿
  3. 4
    Day 4：n8n AI Agent 教學，建立第一位 AI 同事並寫下工作規則
  4. 5
    Day 5：n8n AI Agent 會不會亂猜？用 5 題 Preview 實測
  5. 6
    Day 6：第一個 n8n Workflow Tool，從 Data Table 查專案進度
完整目錄
圖片
  熱門推薦
圖片
{{ item.channelVendor }} | {{ item.webinarstarted }} |
{{ formatDate(item.duration) }}
直播中

尚未有邦友留言

立即登入留言
iThome鐵人賽
參賽組數
929 組
團體組數
32 組
累計文章數
12380 篇
完賽人數
154 人
iT+看影片追技術 看影片追技術 看更多
熱門tag
15th鐵人賽 16th鐵人賽 13th鐵人賽 14th鐵人賽 17th鐵人賽 12th鐵人賽 11th鐵人賽 18th鐵人賽 鐵人賽 2019鐵人賽 javascript 2018鐵人賽 python 2017鐵人賽 windows php c# linux windows server css
熱門問題
熱門回答
熱門文章
IT邦幫忙