n8n Assistant에 필요한 것#

셀프 호스팅 n8n Assistant를 설정하려면 항상 세 가지가 필요합니다.

• 모델 제공자: Anthropic, OpenAI 또는 OpenRouter의 API 키.
• 샌드박스(필수): n8n Assistant가 코드를 실행하는 격리된 환경.
• 검색 제공자(선택 사항): n8n Assistant가 웹에서 정보를 검색할 수 있게 합니다.

샌드박스를 어떻게 제공할지가 가장 중요한 결정입니다. n8n에 기본 포함된 샌드박스(n8n-sandbox)는 로컬 개발과 테스트에 적합합니다. 원라인 설정 명령과 Docker Compose 가이드가 이 샌드박스를 자동으로 설정합니다. 프로덕션에서는 대신 Daytona를 사용하세요.

n8n을 설치한 방법과 실행 위치에 따라 아래 설정 선택하기를 참고하세요.

시작하기 전에#

다음을 준비하세요.

• n8n 인스턴스의 환경 변수를 구성할 수 있는 권한.
• 최신 버전의 n8n. 최신 안정(stable) 릴리즈 이상을 실행하세요. 이전 버전도 동작할 수 있지만 최신 버전을 권장합니다.
• 지원되는 LLM 제공자(Anthropic, OpenAI 또는 OpenRouter)의 API 키.

설정 선택하기#

설정 1: 샌드박스가 이미 실행 중인 경우 (로컬 개발에 권장)#

원라인 설정 명령으로 n8n을 설치했거나 Docker Compose 가이드에 따라 직접 구성했다면, 샌드박스와 번들 SearXNG를 사용하는 검색이 이미 실행 중입니다. 남은 것은 모델 키뿐입니다.

필요한 것: LLM API 키. 그 외에는 필요하지 않습니다.

단계:

가장 빠른 방법은 에디터를 열고 인스턴스의 AI 설정으로 이동해 모델 키를 추가하는 것입니다. .env를 선호한다면 아래 단계를 따르세요.

1. .env에 모델 키를 추가합니다.

   N8N_INSTANCE_AI_MODEL_API_KEY=sk-ant-xxx
   

2. n8n을 재시작합니다.

3. 에디터를 열어 n8n Assistant가 표시되고 응답하는지 확인합니다.

N8N_INSTANCE_AI_MODEL의 기본값은 anthropic/claude-opus-4-8입니다. 다른 모델을 사용하려는 경우에만 명시적으로 설정하세요(모델 제공자 선택하기 참고).

영상으로 보고 싶다면 이 영상 가이드에서 원라인 설치부터 에디터에서 제공자와 모델을 선택하는 것까지 설정 전 과정을 확인할 수 있습니다.

설정 2: 샌드박스를 직접 셀프 호스팅 (고급)#

원라인 설정 명령이나 Docker Compose 가이드 밖에서 n8n을 구성하고 있고, 샌드박스를 Daytona에 맡기지 않고 직접 실행하려는 경우에 사용합니다.

필요한 것:

• n8n에서 접근할 수 있도록 실행 중인 n8n Sandbox Service. 전체 스택(sandbox-certs, sandbox-api, sandbox-runner-1)과 시크릿은 Docker Compose 가이드를 참고하세요.
• LLM API 키.

단계:

1. 샌드박스 스택을 구성합니다(위에 링크된 Docker Compose 가이드).

2. 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
   

   변수	설명
   N8N_INSTANCE_AI_SANDBOX_ENABLED	true로 설정합니다.
   N8N_INSTANCE_AI_SANDBOX_PROVIDER	n8n-sandbox로 설정합니다.
   N8N_SANDBOX_SERVICE_URL	n8n에서 접근할 수 있는 샌드박스 API의 URL.
   N8N_SANDBOX_SERVICE_API_KEY	API 컨테이너의 SANDBOX_API_KEYS와 일치해야 합니다.

3. 모델 키를 추가(모델 제공자 선택하기 참고)하고 n8n을 재시작합니다.

확인:

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

예상 응답: {"status":"ok"}

참고 사항:

• my-sandbox-api-key를 직접 만든 시크릿으로 바꾸고, API 컨테이너와 러너 컨테이너에 서로 일치하는 등록 토큰(registration-token) 및 러너 키(runner-key) 시크릿을 설정하세요. 전체 변수 목록과 연결 방식은 Docker Compose 가이드를 참고하세요.
• N8N_SANDBOX_SERVICE_API_KEY는 샌드박스 API 컨테이너의 SANDBOX_API_KEYS에 있는 값 중 하나와 일치해야 합니다.
• 러너는 처음 사용할 때 샌드박스 이미지를 가져옵니다. 에어 갭(air-gapped) 환경에서는 해당 이미지를 러너의 내부 Docker에 미리 로드하세요.
• 호스트 이름이 중요합니다. 인증서는 sandbox-api와 sandbox-runner-<n>에 대해 발급되므로, 이 서비스 이름을 유지하거나 일치하는 SAN으로 인증서를 다시 생성하세요.

설정 3: Daytona (관리형 샌드박스, 프로덕션에 권장)#

Daytona는 컨테이너를 직접 호스팅하는 대신 필요할 때 샌드박스를 생성합니다. n8n이 프로덕션 사용에 권장하는 샌드박스 제공자입니다.

필요한 것: Daytona 계정과 API 키, 그리고 LLM API 키.

단계:

1. n8n 인스턴스에 다음 환경 변수를 설정합니다.

   # Enable the module and choose a model
   N8N_ENABLED_MODULES=instance-ai
   N8N_INSTANCE_AI_MODEL=anthropic/claude-opus-4-8
   N8N_INSTANCE_AI_MODEL_API_KEY=sk-ant-xxx
   
   # Sandbox, required
   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
   
   # Web search, recommended
   INSTANCE_AI_BRAVE_SEARCH_API_KEY=BSA-xxx
   

   변수	설명
   N8N_ENABLED_MODULES	모듈을 활성화하려면 instance-ai를 포함해야 합니다.
   N8N_INSTANCE_AI_MODEL	provider/model 형식으로 LLM을 선택합니다. 기본값(anthropic/claude-opus-4-8)이 있습니다. 다른 모델을 사용하려는 경우에만 명시적으로 설정하세요.
   N8N_INSTANCE_AI_MODEL_API_KEY	선택한 제공자의 API 키.
   N8N_INSTANCE_AI_SANDBOX_ENABLED	true로 설정합니다. n8n Assistant에는 샌드박스가 필요합니다.
   N8N_INSTANCE_AI_SANDBOX_PROVIDER	daytona로 설정합니다.
   N8N_INSTANCE_AI_SANDBOX_IMAGE	Daytona 샌드박스의 기본 컨테이너 이미지.
   DAYTONA_API_URL	Daytona API 엔드포인트.
   DAYTONA_API_KEY	Daytona API 키.
   INSTANCE_AI_BRAVE_SEARCH_API_KEY	웹 검색용 Brave Search API 키. 이 변수는 의도적으로 N8N_ 접두사를 사용하지 않습니다.

   Docker Compose 예시:

   services:
     n8n:
       image: 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
   

2. n8n을 재시작하고 에디터를 열어 n8n Assistant가 표시되고 응답하는지 확인합니다.

선택 사항: 샌드박스 수명 주기 조정

N8N_INSTANCE_AI_SANDBOX_AUTO_STOP_MINUTES=15
N8N_INSTANCE_AI_SANDBOX_AUTO_ARCHIVE_MINUTES=60
N8N_INSTANCE_AI_SANDBOX_AUTO_DELETE_MINUTES=10080

모델 제공자 선택하기#

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 키가 필요하지 않습니다.

웹 검색 활성화하기#

웹 검색을 사용하면 n8n Assistant가 웹에서 정보를 찾아볼 수 있습니다. 선택 사항이며, 웹 검색 없이도 n8n Assistant의 나머지 기능은 동작합니다.

원라인 설정 또는 Docker Compose 가이드를 사용했다면 SearXNG가 이미 번들로 포함되어 실행 중입니다. Brave Search를 대신 사용하려는 경우가 아니라면 별도 설정이 필요하지 않습니다.

# Brave Search
INSTANCE_AI_BRAVE_SEARCH_API_KEY=BSA-xxx

# SearXNG
N8N_INSTANCE_AI_SEARXNG_URL=http://searxng:8080

둘 다 구성하면 Brave Search가 SearXNG보다 우선합니다. SearXNG를 포함한 무료 또는 인증 없는 제공자는 속도 제한(rate limit)에 걸릴 수 있으므로, 더 안정적으로 구성하려면 Brave Search를 사용하세요.

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

인스턴스 컨텍스트 활성화하기#

인스턴스 컨텍스트는 대화를 시작한 프로젝트의 간단한 요약을 n8n Assistant에 제공합니다. 요약에는 워크플로, 최근 변경 사항, 실행 결과가 포함됩니다. 선택 사항이며, 인스턴스 컨텍스트 없이도 n8n Assistant의 나머지 기능은 동작합니다. n8n Assistant가 인스턴스에 대해 아는 것을 참고하세요.

114_instance_activity_context PostHog 플래그가 이를 제어합니다. n8n은 이 플래그를 사용자별이 아니라 인스턴스별로 평가합니다. 같은 플래그가 활동 기록, n8n Assistant의 인스턴스 컨텍스트, n8n MCP 서버의 인스턴스 컨텍스트 도구를 모두 제어합니다.

셀프 호스팅 인스턴스에서는 N8N_FEATURE_FLAG_OVERRIDES를 설정해 PostHog 값을 재정의할 수 있습니다. 예를 들어 .env 파일에 이 값을 추가합니다. JSON 객체의 다른 항목은 그대로 유지하세요.

N8N_FEATURE_FLAG_OVERRIDES='{"114_instance_activity_context":true}'

변경 사항을 적용하려면 n8n을 재시작합니다.

PostHog 플래그 평가에 실패하면, 유효한 재정의가 기능을 켜지 않는 한 기능은 꺼집니다.

하나의 플래그가 두 기능을 모두 제어합니다. 플래그가 꺼져 있으면 n8n은 활동 항목을 기록하지 않고 n8n Assistant는 인스턴스 컨텍스트를 읽지 않습니다.

활동 로그는 변경이 발생했다는 사실과 그 변경에서 추가하거나 제거한 노드 유형을 기록합니다. 파라미터 값은 절대 기록하지 않습니다. 프로젝트가 현재 무엇을 사용하는지가 아니라, 저장 시 무엇이 바뀌었는지를 보고합니다. 노드 유형 집계는 현재 사용량을 보고하며, 별도의 플래그가 필요합니다.

플래그를 끄면 새 활동 기록과 새 인스턴스 컨텍스트 읽기가 중지됩니다. 활동 로그 도구는 사용할 수 없게 됩니다. 이전에 기록된 항목에는 계속 다음 보존 설정이 적용됩니다.

기본적으로 n8n은 인스턴스 전체에서 최신 활동 항목 1,000개를 보관합니다. 기간을 기준으로 항목을 삭제하지는 않습니다. 로그가 이 한도 아래로 유지되면 항목이 무기한 남아 있을 수 있습니다.

정리는 매시간 실행되며 플래그가 꺼져 있어도 계속됩니다. 이 환경 변수를 변경한 후에는 n8n을 재시작하세요.

노드 유형 집계 활성화하기#

노드 유형 집계를 사용하면 n8n Assistant가 프로젝트에서 각 노드 유형을 사용하는 워크플로가 몇 개인지 물어볼 수 있어, 모든 워크플로를 읽지 않고도 사용자의 관례를 따를 수 있습니다. 인스턴스 컨텍스트와는 별개이며 자체 플래그가 있습니다.

109_instance_ai_node_usage PostHog 플래그가 이를 제어합니다. 셀프 호스팅 인스턴스에서는 N8N_INSTANCE_AI_NODE_USAGE_ENABLED로 강제로 활성화할 수 있습니다.

N8N_INSTANCE_AI_NODE_USAGE_ENABLED=true

이 변수는 노드 유형 집계를 켜기만 합니다. false로 설정하거나 생략하면 결정이 PostHog 플래그로 돌아가므로, 기능을 꺼 두는 방법이 아닙니다.

노드 유형 집계는 노드 유형의 개수만 보고하며 파라미터 값은 절대 보고하지 않습니다.

에이전트 활성화하기#

n8n Assistant 사용 여부와 관계없이 인스턴스에서 에이전트를 빌드하고 실행할 수 있습니다. 에이전트는 미리보기(Preview) 상태이며 n8n 2.32.3부터 사용할 수 있습니다.

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

인스턴스 설정을 변경하려면 다음을 따릅니다.

1. 인스턴스 소유자 또는 관리자로 로그인합니다.
2. Settings > Agents를 엽니다.
3. Enable Agents를 켜거나 끕니다.

n8n은 이 선택을 재시작과 라이선스 변경 후에도 유지합니다. 이 설정은 Settings > Assistant와 별개입니다. 에이전트를 끄면 새 실행이 차단되고, 이후 실행을 위해 대기 중인 메시지가 취소됩니다. 진행 중인 실행은 끝까지 완료될 수 있습니다. 자세한 내용은 에이전트 활성화 또는 비활성화를 참고하세요.

agents 모듈은 기본적으로 로드됩니다. N8N_DISABLED_MODULES로 비활성화했다면, 해당 목록에서 agents를 제거하고 n8n을 재시작해 설정 페이지를 복원하세요. 모듈 환경 변수는 저장된 에이전트 설정을 재정의하지 않습니다.

공유 샌드박스와 선택 기능#

Settings > Agents > Shared sandbox를 사용해 샌드박스 연결을 구성합니다. 에이전트와 n8n Assistant가 같은 연결을 사용하므로, 변경 사항은 두 기능 모두에 영향을 줍니다. 어느 한 기능이 꺼져 있어도 구성할 수 있습니다.

공유 샌드박스 편집기에는 instance-ai 모듈이 필요하며, 이 모듈도 기본적으로 로드됩니다. N8N_DISABLED_MODULES로 제외했다면 해당 목록에서 제거하고 n8n을 재시작하세요. Settings > Assistant에서 n8n Assistant를 꺼 둔 상태로 유지해도 됩니다. 환경 변수로 샌드박스를 구성할 수도 있습니다.

공유 샌드박스를 활성화하면 에이전트 지식 베이스(knowledge base)도 함께 활성화됩니다. 환경 변수 기반 설정에서는 다음 선택적 설정을 사용합니다.

# Enable the agent knowledge base with your existing Daytona connection
N8N_AGENTS_AI_SANDBOX_ENABLED=true
N8N_INSTANCE_AI_SANDBOX_PROVIDER=daytona

# Let channels reach your instance
N8N_WEBHOOK_URL=https://<your-public-hostname>

전체 배포 예시는 설치 옵션을 참고하세요. 첫 에이전트를 만들려면 에이전트 빌드 및 관리를 참고하세요.

n8n Assistant 비활성화하기#

n8n Assistant를 끄려면 Settings > Assistant를 사용합니다. 모듈을 언로드하려면 N8N_DISABLED_MODULES에 instance-ai를 추가하고 n8n을 재시작합니다.

N8N_DISABLED_MODULES=instance-ai

instance-ai를 언로드하면 Settings > Agents의 공유 샌드박스 편집기도 함께 사라집니다. 환경 변수로는 계속 샌드박스를 구성할 수 있습니다.

문제 해결#

n8n Assistant가 표시되지 않거나 동작하지 않으면 다음 항목을 확인하세요.

일반

• N8N_DISABLED_MODULES에 instance-ai가 포함되어 있지 않은지 확인합니다.
• N8N_INSTANCE_AI_MODEL을 설정했다면 모델 값이 provider/model 형식인지 확인합니다.
• 선택한 제공자에 유효한 API 키인지 확인합니다.
• N8N_INSTANCE_AI_SANDBOX_ENABLED가 true로 설정되어 있는지 확인합니다.

셀프 호스팅 샌드박스(설정 2)

• N8N_SANDBOX_SERVICE_API_KEY가 API 컨테이너의 SANDBOX_API_KEYS와 일치하는지 확인합니다.
• 샌드박스 상태 점검(health check)이 {"status":"ok"}를 반환하는지 확인합니다.
• n8n 컨테이너에서 N8N_SANDBOX_SERVICE_URL에 접근할 수 있는지 확인합니다.

Daytona(설정 3)

• DAYTONA_API_URL과 DAYTONA_API_KEY가 설정되어 있는지 확인합니다.
• Daytona 계정에 새 샌드박스를 생성할 여유 용량이 있는지 확인합니다.

웹 검색

• INSTANCE_AI_BRAVE_SEARCH_API_KEY 또는 N8N_INSTANCE_AI_SEARXNG_URL이 설정되어 있는지 확인합니다.
• 아무것도 설정하지 않았다면 정상입니다. 웹 검색은 선택 사항이며 n8n Assistant의 나머지 기능은 계속 동작합니다.

인스턴스 컨텍스트

• 인스턴스에서 114_instance_activity_context 플래그가 켜져 있는지 확인합니다. 강제로 켜려면 N8N_FEATURE_FLAG_OVERRIDES를 {"114_instance_activity_context":true}로 설정하세요.
• 아직 프로젝트에 변경 사항이 없을 수 있습니다. 활동 로그는 플래그가 켜진 이후의 변경만 기록합니다.
• 프로젝트가 비어 있고 아무것도 실행되지 않았을 수 있습니다. 이 경우 n8n Assistant는 빈 요약을 보여 주지 않고 아무것도 보고하지 않습니다.

노드 유형 집계

• 109_instance_ai_node_usage 플래그가 켜져 있거나 N8N_INSTANCE_AI_NODE_USAGE_ENABLED 값이 true인지 확인합니다.
• 변수를 false로 설정해도 기능이 꺼진 상태로 유지되지 않습니다. 결정이 플래그로 돌아갑니다.
• 인스턴스 컨텍스트와는 독립적입니다. 인스턴스 컨텍스트를 켜도 노드 유형 집계는 켜지지 않습니다.

관련 리소스#

• n8n 구성하기