셀프 호스팅 인스턴스에서 AI Assistant를 실행하려면 다음이 필요합니다.

• LLM 제공업체의 API 키.
• AI 모델. n8n은 기본적으로 anthropic/claude-opus-4-8을 사용하며, 직접 설정할 수도 있습니다.
• 샌드박스 제공업체. Daytona를 권장합니다.
• 웹 검색을 원하는 경우 검색 제공업체. Brave Search를 권장합니다.

시작하기 전에#

다음을 준비했는지 확인하세요.

• n8n 인스턴스의 환경 변수를 설정할 수 있는 권한.
• 최신 버전의 n8n. 최신 안정 릴리즈 이상을 실행하세요. 이전 버전에서도 동작할 수 있지만, 최신 버전이 더 좋습니다.
• 지원되는 LLM 제공업체의 API 키:
  • Anthropic
  • OpenAI
  • OpenRouter
• 샌드박스 제공업체. Daytona를 권장합니다.
• 웹 검색을 원하는 경우 검색 제공업체. Brave Search를 권장합니다.

Daytona로 빠르게 설정하기#

Daytona는 대부분의 셀프 호스팅 설정에 권장되는 샌드박스 제공업체입니다.

이 설정은 Anthropic 모델, Daytona, 그리고 웹 검색을 위한 Brave Search와 함께 AI Assistant를 활성화합니다.

n8n 인스턴스에 다음 환경 변수를 설정하세요.

# 모듈을 활성화하고 모델을 선택합니다
N8N_ENABLED_MODULES=instance-ai
N8N_INSTANCE_AI_MODEL=anthropic/claude-opus-4-8
N8N_INSTANCE_AI_MODEL_API_KEY=sk-ant-xxx

# 샌드박스, 필수
N8N_INSTANCE_AI_SANDBOX_ENABLED=true
N8N_INSTANCE_AI_SANDBOX_PROVIDER=daytona
N8N_INSTANCE_AI_SANDBOX_IMAGE=daytonaio/sandbox:0.5.3-slim

# Daytona
DAYTONA_API_URL=https://app.daytona.io/api
DAYTONA_API_KEY=dtn_xxx

# 웹 검색, 권장
INSTANCE_AI_BRAVE_SEARCH_API_KEY=BSA-xxx

이 변수들은 다음과 같은 역할을 합니다.

Docker Compose 예시#

services:
  n8n:
    image: docker.n8n.io/n8nio/n8n
    environment:
      N8N_ENABLED_MODULES: instance-ai
      N8N_INSTANCE_AI_MODEL: anthropic/claude-opus-4-8
      N8N_INSTANCE_AI_MODEL_API_KEY: sk-ant-xxx
      N8N_INSTANCE_AI_SANDBOX_ENABLED: 'true'
      N8N_INSTANCE_AI_SANDBOX_PROVIDER: daytona
      N8N_INSTANCE_AI_SANDBOX_IMAGE: daytonaio/sandbox:0.5.3-slim
      DAYTONA_API_URL: https://app.daytona.io/api
      DAYTONA_API_KEY: dtn_xxx
      INSTANCE_AI_BRAVE_SEARCH_API_KEY: BSA-xxx

적용 및 확인#

변수를 설정한 후:

1. 모든 n8n 프로세스를 재시작합니다.
2. 편집기를 엽니다.
3. AI Assistant가 나타나고 응답하는지 확인합니다.

모델 제공업체 선택#

N8N_INSTANCE_AI_MODEL은 다음 형식을 사용합니다.

provider/model

지원되는 제공업체는 다음과 같습니다.

• anthropic
• openai
• openrouter

호스팅형 제공업체를 사용하려면 anthropic/claude-opus-4-8 또는 openai/gpt-5.5부터 시작하세요.

예시:

# Anthropic
N8N_INSTANCE_AI_MODEL=anthropic/claude-opus-4-8

# OpenAI
N8N_INSTANCE_AI_MODEL=openai/gpt-5.5

# OpenRouter
N8N_INSTANCE_AI_MODEL=openrouter/deepseek/deepseek-v4-pro

N8N_INSTANCE_AI_MODEL_API_KEY를 선택한 제공업체의 API 키로 설정하세요.

N8N_INSTANCE_AI_MODEL_API_KEY가 설정되어 있지 않으면, n8n은 대체 값으로 제공업체의 표준 환경 변수를 사용합니다.

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• OPENROUTER_API_KEY

로컬 또는 사용자 지정 OpenAI 호환 엔드포인트 사용하기#

로컬 또는 사용자 지정 OpenAI 호환 엔드포인트를 사용하려면 N8N_INSTANCE_AI_MODEL_URL을 설정하세요.

N8N_INSTANCE_AI_MODEL_URL=http://localhost:1234/v1
N8N_INSTANCE_AI_MODEL_API_KEY=optional-key

일부 로컬 서버는 API 키가 필요하지 않습니다.

샌드박스 제공업체 구성하기#

AI Assistant는 격리된 샌드박스 내에서 작업을 실행하므로 샌드박스 제공업체가 필요합니다.

옵션 A: Daytona#

Daytona로 빠르게 설정하기를 따랐다면, 필요한 Daytona 변수가 이미 준비되어 있습니다.

Daytona는 필요할 때마다 샌드박스를 생성합니다.

다음 변수로 샌드박스 라이프사이클을 조정하세요.

N8N_INSTANCE_AI_SANDBOX_AUTO_STOP_MINUTES=15
N8N_INSTANCE_AI_SANDBOX_AUTO_ARCHIVE_MINUTES=60
N8N_INSTANCE_AI_SANDBOX_AUTO_DELETE_MINUTES=10080

옵션 B: n8n Sandbox Service#

샌드박스 서비스를 직접 호스팅하려면 n8n Sandbox Service를 사용하세요.

n8n Sandbox Service에는 두 개의 컨테이너가 있습니다.

• n8nio/n8n-sandbox-service-api: n8n이 통신하는 HTTP API입니다.
• n8nio/n8n-sandbox-service-runner-dind: 샌드박스를 Docker-in-Docker 컨테이너로 실행하는 러너입니다.

API와 러너는 mutual TLS로 통신합니다. API 이미지에는 인증서를 생성하는 bootstrap-mtls.sh 스크립트가 포함되어 있습니다.

전체 Docker Compose 예시#

n8n 서비스와 함께 이것을 실행하세요.

volumes:
  sandbox-tls:

services:
  # 일회성: mTLS 인증서를 생성한 후 종료됩니다
  sandbox-certs:
    image: n8nio/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 --world-readable &&
        chown -R sandbox-api:sandbox-api /tls/api && chmod -R a+rX /tls
    environment:
      NUM_RUNNERS: '1'
    volumes:
      - sandbox-tls:/tls

  sandbox-api:
    image: n8nio/n8n-sandbox-service-api:latest
    depends_on:
      sandbox-certs:
        condition: service_completed_successfully
    environment:
      SANDBOX_API_KEYS: my-sandbox-api-key
      SANDBOX_API_RUNNER_REGISTRATION_TOKEN: my-registration-token
      SANDBOX_API_RUNNER_API_KEY: my-runner-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

  sandbox-runner-1:
    image: n8nio/n8n-sandbox-service-runner-dind:latest
    privileged: true
    depends_on:
      - sandbox-api
    environment:
      SANDBOX_RUNNER_API_KEYS: my-runner-key
      SANDBOX_RUNNER_REGISTRATION_TOKEN: my-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: n8nio/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을 샌드박스 서비스로 지정하기#

서비스가 실행되면, n8n 인스턴스에 다음 변수를 설정하세요.

N8N_INSTANCE_AI_SANDBOX_ENABLED=true
N8N_INSTANCE_AI_SANDBOX_PROVIDER=n8n-sandbox
N8N_SANDBOX_SERVICE_URL=http://sandbox-api:8080
N8N_SANDBOX_SERVICE_API_KEY=my-sandbox-api-key

서비스가 실행 중인지 확인하세요.

curl http://<sandbox-api-host>:8080/healthz

예상 응답:

{"status":"ok"}

참고 사항:

• my-sandbox-api-key, my-registration-token, my-runner-key를 사용자 고유의 시크릿으로 교체하세요.
• 러너는 처음 사용할 때 Docker Hub에서 n8nio/n8n-sandbox-service-sandbox를 가져옵니다.
• 에어갭 환경의 경우, n8nio/n8n-sandbox-service-sandbox를 러너의 내부 Docker에 미리 로드하세요.
• 호스트 이름이 중요합니다. 인증서는 sandbox-api와 sandbox-runner-<n>에 대해 발급되므로, 해당 서비스 이름을 그대로 유지하거나 일치하는 SAN으로 인증서를 재생성하세요.

선택적 기능#

기본 설정이 동작한 후, 웹 검색을 조정할 수 있습니다.

웹 검색 활성화하기#

웹 검색을 사용하면 AI Assistant가 웹에서 정보를 조회할 수 있습니다. 이를 위해서는 검색 제공업체가 필요합니다.

Brave Search가 권장 제공업체입니다. 권장 설정에는 기본적으로 Brave Search가 포함됩니다. 웹 검색을 구성하지 않아도 AI Assistant의 나머지 기능은 계속 동작하지만, 웹 검색 액션은 비활성화 상태로 유지됩니다.

# Brave Search
INSTANCE_AI_BRAVE_SEARCH_API_KEY=BSA-xxx

# SearXNG
N8N_INSTANCE_AI_SEARXNG_URL=http://searxng:8080

웹 검색을 원한다면 Brave Search를 구성하세요. SearXNG도 함께 구성한 경우, Brave Search가 SearXNG보다 우선합니다.

SearXNG를 포함한 무료 또는 인증되지 않은 제공업체는 속도 제한(rate limit)에 걸릴 수 있습니다. 더 안정적인 설정을 위해 Brave Search를 사용하세요.

인스턴스 관리자가 AI 설정 UI에서 Brave Search 또는 SearXNG 자격 증명을 선택하면, n8n은 이 환경 변수 대신 해당 자격 증명을 사용합니다.

에이전트 활성화하기#

에이전트는 AI Assistant와 동일한 셀프 호스팅 스택에서 실행됩니다. AI Assistant가 동작하면, agents 모듈을 추가하여 인스턴스에서 에이전트를 빌드하고 실행할 수 있습니다. 에이전트에는 n8n 2.32.3(Beta) 이상이 필요합니다.

agents 모듈만으로 에이전트를 수동으로 빌드합니다. 모델을 선택하고, 지침을 작성하고, 도구와 스킬을 직접 연결합니다. AI Assistant(instance-ai)는 선택 사항이며, 에이전트를 설명하면 n8n이 이를 스캐폴딩해주는 AI 지원 빌드 기능을 추가합니다.

AI 지원 빌드를 원한다면 instance-ai와 함께 N8N_ENABLED_MODULES에 agents를 추가하세요.

# 에이전트 모듈을 활성화합니다(AI 지원 빌드를 위해 instance-ai를 유지합니다)
N8N_ENABLED_MODULES=instance-ai,agents

# 지식 베이스, 선택 사항: AI Assistant용으로 설정한 Daytona 샌드박스를 재사용합니다
N8N_AGENTS_AI_SANDBOX_ENABLED=true
N8N_AGENTS_AI_SANDBOX_PROVIDER=daytona

# 채널, 선택 사항: Slack, Telegram, Linear가 인스턴스에 접근할 수 있도록 하는 공개 URL
WEBHOOK_URL=https://your-public-url

전체 배포 예시는 설치 옵션을 참고하세요. 모듈을 활성화한 후에는 에이전트 빌드 및 관리를 참고하세요.

AI Assistant 비활성화하기#

AI Assistant를 비활성화하려면 N8N_ENABLED_MODULES에서 instance-ai를 제거하세요.

다음과 같이 모듈을 명시적으로 비활성화할 수도 있습니다.

N8N_DISABLED_MODULES=instance-ai

문제 해결#

AI Assistant가 나타나지 않거나 동작하지 않는 경우, 다음을 확인하세요.

• N8N_ENABLED_MODULES에 instance-ai가 포함되어 있는지.
• N8N_INSTANCE_AI_MODEL을 설정한 경우, 모델 값이 provider/model 형식을 사용하는지.
• API 키가 선택한 제공업체에 유효한지.
• N8N_INSTANCE_AI_SANDBOX_ENABLED가 true로 설정되어 있는지.
• 샌드박스 제공업체가 구성되어 있는지.
• 샌드박스 제공업체가 n8n 인스턴스에서 접근 가능한지.
• Daytona의 경우, DAYTONA_API_URL과 DAYTONA_API_KEY가 설정되어 있는지.
• 웹 검색을 원하는 경우, INSTANCE_AI_BRAVE_SEARCH_API_KEY가 설정되어 있는지, 또는 N8N_INSTANCE_AI_SEARXNG_URL이 설정되어 있는지.
• n8n Sandbox Service의 경우, N8N_SANDBOX_SERVICE_API_KEY가 API 컨테이너의 SANDBOX_API_KEYS와 일치하는지.
• 샌드박스 서비스 상태 확인(health check)이 {"status":"ok"}를 반환하는지.