n8n 문서, 어디부터 봐야 할까요? 리뉴얼된 Docs를 길잡이처럼 쓰는 법
n8n을 처음 쓰면 도구보다 문서에서 먼저 길을 잃습니다. Cloud로 시작할지 Docker로 띄울지, Webhook과 Expression은 언제 읽어야 할지, Google Sheets 설정은 어디서 찾는지. 최근 리뉴얼된 n8n Docs는 이 질문을 메뉴 하나로 끝내진 않지만 지금 하려는 일을 기준으로 시작점을 고르게 해줍니다. Claude Code나 Codex 같은 코딩 에이전트를 n8n에 연결하는 방법도 이번 리뉴얼에서 Connect 메뉴에 정식으로 자리 잡았습니다.
화면이 바뀐 것보다, 시작 순서가 바뀐 것이 더 큽니다
n8n Docs 저장소에는 2026년 6월 24일 GitBook Docs Release 커밋이 반영됐습니다. 새 문서에서 눈에 띄는 점은 메뉴가 기능 목록보다 사용자의 다음 행동에 가깝게 정리됐다는 것입니다.
이전처럼 검색 결과에서 노드 문서 한 장을 바로 열어도 됩니다. 다만 처음 시작하는 사람에게는 그 방식이 잘 맞지 않습니다. Slack Trigger 옵션을 읽는다고 해서 워크플로우가 어떻게 시작되고 데이터가 어디로 흘러가는지까지 이해되지는 않기 때문입니다.
리뉴얼된 구조는 먼저 큰 흐름을 보여주고 필요한 순간에 세부 문서로 내려가게 합니다. 메뉴마다 역할이 다릅니다.
설치는 나중, Get started에서 시작 방식부터 정합니다
Get started는 n8n을 처음 열었을 때 가장 먼저 볼 메뉴입니다. 여기에는 Cloud 체험, npm과 Docker 설치, 첫 워크플로우 만들기, 핵심 개념, 학습 경로가 모여 있습니다.
처음부터 셀프호스팅 설정을 오래 붙잡을 필요는 없습니다. 자동화를 배우는 것이 목적이라면 n8n Cloud나 실행 가능한 로컬 환경으로 먼저 들어가 워크플로우를 하나 돌려보는 편이 낫습니다. 인프라 운영과 자동화 설계를 한꺼번에 배우면 둘 다 늦어집니다.
Choose how to use n8n은 Cloud와 Self-hosted 중 무엇을 고를지 정리해 둔 페이지입니다. 빠르게 시작하고 운영 부담을 줄이고 싶다면 Cloud, 서버와 데이터·보안 정책을 직접 통제해야 한다면 Self-hosted가 출발점이 됩니다.
Get started/
├─ Get started (개요)
├─ Choose how to use n8n (Cloud·Self-hosted 선택)
├─ Build your first workflow (첫 워크플로우 만들기)
├─ Learning paths (학습 경로)
└─ Key concept glossary (핵심 개념 용어집)
Deploy는 워크플로우가 돌아간 뒤를 다룹니다
Deploy는 n8n을 어디에서 어떻게 운영할지 다룹니다. Cloud 요금제, Docker 같은 설치 방법, 클라우드 제공업체 배포, 확장 방식, 셀프호스팅 운영 항목이 여기에 있습니다.
이 메뉴는 초보자가 첫날부터 끝까지 읽을 곳은 아닙니다. 다만 다음 질문이 생기면 바로 여기로 오면 됩니다.
- 우리 팀 데이터가 외부 SaaS에 남아도 되는가
- n8n을 사내 서버나 VPC 안에 두어야 하는가
- 실행량이 늘면 어떤 방식으로 확장해야 하는가
- 백업, 보안, 업그레이드를 누가 맡는가
자동화가 한두 개일 때는 워크플로우 화면이 중심입니다. 고객 데이터, 반복 실행, 팀 계정이 붙기 시작하면 배포 방식이 결과의 일부가 됩니다. 그때 Deploy 문서를 읽으면 됩니다.
Deploy/
├─ n8n Cloud (클라우드로 시작)
│ ├─ Start your free trial (무료 체험 시작)
│ ├─ Use the admin dashboard (관리 대시보드 사용)
│ ├─ Update your version (버전 업데이트)
│ ├─ Configure Cloud (Cloud 설정)
│ ├─ Understand concurrency (동시 실행 이해)
│ └─ Download workflows (워크플로우 다운로드)
└─ Self-hosted n8n (셀프호스팅)
├─ Install options (설치 방법)
├─ Configure n8n (n8n 설정)
├─ Keep n8n running (안정적으로 운영하기)
├─ Understand the architecture (아키텍처 이해)
├─ Deploy as an OEM integration (OEM 통합 배포)
├─ Deploy with the AI starter kit (AI 스타터 키트로 배포)
└─ Community edition features (커뮤니티 에디션 기능)
자동화의 본체는 Build에서 만듭니다
Build는 워크플로우를 조립하는 데 필요한 개념을 모아 둔 곳입니다. 데이터가 노드 사이를 어떻게 지나가는지, 조건을 어떻게 나누는지, 목록 데이터를 어떻게 처리하는지, Expression으로 이전 노드 값을 어떻게 꺼내는지, AI 기능을 어떤 흐름에 붙이는지를 다룹니다.
처음에 꼭 잡아둘 단어는 여섯 개면 충분합니다.
- Trigger: 워크플로우를 시작하는 신호
- Node: 데이터를 처리하거나 서비스를 호출하는 작업 단위
- Connection: 노드 사이 데이터가 흐르는 선
- Execution: 한 번 실행된 워크플로우의 기록
- Credentials: API 키·OAuth 같은 인증 정보
- Expression: 이전 노드의 값을 꺼내고 가공하는 문법
Build your first workflow는 이 메뉴로 들어가기 전의 좋은 연습입니다. 트리거 하나, 처리 노드 하나, 결과를 확인할 노드 하나를 연결하고 실제 실행해 보면, 이후 Build의 설명이 추상적인 용어가 아니라 화면에서 본 동작으로 바뀝니다.
AI Agent부터 바로 시작하는 것은 추천하지 않습니다. AI 노드도 결국 입력 데이터, 분기, 외부 서비스 호출, 오류 처리 위에서 돌아갑니다. 이 기본 흐름을 먼저 익히면 AI를 붙였을 때 어디가 실패했는지도 찾기 쉬워집니다.
Build/
├─ Understand workflows (워크플로우 이해하기)
├─ Build and manage agents (에이전트 만들고 관리하기)
├─ Ways of building workflows (워크플로우 제작 방식)
├─ Manage workflows (워크플로우 관리)
├─ Flow logic (흐름 제어 로직)
├─ Work with data (데이터 다루기)
├─ Code in n8n (n8n에서 코드 쓰기)
├─ Integrate AI (AI 통합)
└─ Keyboard shortcuts (단축키)
서비스별 설정값은 Nodes에서 찾습니다
Nodes는 Google Sheets, Slack, Gmail, Notion, HTTP Request처럼 특정 노드의 설정값과 동작을 찾는 곳입니다. 필요한 서비스가 분명할 때 가장 빨리 답을 얻을 수 있습니다.
예를 들어 “Google Sheets에 행을 추가하고 싶다”면 Google Sheets 노드 문서에서 operation과 입력 필드를 확인합니다. “Slack에서 이벤트가 올 때 시작하고 싶다”면 Slack Trigger 문서에서 이벤트와 인증 방식을 봅니다.
여기서 중요한 습관은 노드 이름만 검색하지 않는 것입니다. Google Sheets append row, Slack Trigger event, HTTP Request pagination처럼 노드 이름 + 하려는 일을 같이 넣으면 원하는 문서에 더 빨리 닿습니다.
노드 문서는 기능의 범위와 필수 옵션을 확인하는 곳입니다. 워크플로우 전체 설계를 처음부터 배울 때보다, 실제로 특정 노드 앞에서 막혔을 때 열어보는 편이 효과적입니다.
Nodes/
├─ Built-in nodes (내장 노드 — Google Sheets, Slack, HTTP Request 등 서비스별 노드 전체)
└─ Community nodes (커뮤니티 노드 — 설치·관리 방법)
인증 문제는 Connect에서 따로 봅니다
Connect는 외부 서비스와 n8n을 연결할 때 필요한 내용을 찾는 메뉴입니다. OAuth, API 키, credential 설정, 서비스별 연결 방식처럼 “노드는 보이는데 실행이 안 된다”는 문제와 자주 만납니다.
특히 OAuth는 화면을 보고 추측해서 설정하면 시간이 오래 걸립니다. Redirect URL, 권한 범위(scope), 앱 등록 위치는 서비스마다 다릅니다. 이때는 해당 서비스의 연결 문서와 n8n credential 문서를 함께 보면서 공식 표기를 그대로 따라가는 편이 안전합니다.
실무에서는 인증 문제를 워크플로우 로직 문제로 오해하기 쉽습니다. 실행 기록에서 401, 403, redirect URL 오류가 나오면 노드를 다시 만들기 전에 Connect와 해당 서비스 문서를 먼저 확인하세요.
Connect/
├─ n8n API (n8n API 연동)
├─ n8n CLI (n8n CLI 사용)
├─ Connect to n8n MCP server (n8n MCP 서버 연결)
├─ Connect to n8n docs MCP server (n8n 문서 MCP 서버 연결)
└─ Create nodes (직접 노드 만들기)
이 메뉴에서 눈여겨볼 부분은 Connect to n8n MCP server입니다. n8n은 인스턴스 단위로 MCP 서버를 켤 수 있고, Claude Desktop·Lovable·Google ADK뿐 아니라 Claude Code와 Codex CLI도 공식 연결 대상으로 문서화돼 있습니다. OAuth2나 Access Token으로 인증한 뒤 claude.json이나 ~/.codex/config.toml에 n8n 인스턴스 주소를 등록하면, 코딩 에이전트가 워크플로우를 검색·생성·수정할 수 있습니다.
여기에 더해 n8n-io/skills 저장소는 Expression 문법, 노드 설정, 에러 핸들링 같은 n8n 고유 규칙을 정리한 스킬 모음을 제공합니다. Claude Code나 Codex에 이 스킬을 설치해 두면, 에이전트가 MCP로 워크플로우를 만들 때 n8n 컨벤션을 따라가면서 시행착오를 줄입니다.
팀·보안·실행 기록이 필요해지면 Administer
Administer는 개인 실습 단계보다 팀 운영 단계에서 더 자주 열게 되는 메뉴입니다. 사용자와 프로젝트, 역할과 권한, 보안, 실행 데이터, 모니터링, 환경 설정을 다룹니다.
자동화가 업무에 붙으면 “돌아간다”만으로 충분하지 않습니다. 누가 credential을 관리하는지, 실패한 실행을 누가 보는지, 퇴사자 계정은 어떻게 정리하는지, 민감한 실행 데이터를 얼마나 보관하는지가 함께 중요해집니다.
처음부터 모든 운영 기능을 외울 필요는 없습니다. 다만 팀에서 쓰는 워크플로우를 만들기 시작한다면, 배포 뒤에 Administer를 한 번 훑어보는 것이 좋습니다. 개인 자동화와 운영 자동화의 차이는 이 부분에서 생깁니다.
Administer/
├─ Manage users and access (사용자·권한 관리)
├─ Manage credentials (자격 증명 관리)
├─ Use source control and environments (소스 관리·환경 구성)
└─ Observe and log (모니터링·로그)
Contribute, 문서 끝이 아니라 커뮤니티 입구입니다
Contribute는 n8n 문서나 노드, 커뮤니티에 기여하려는 사람을 위한 메뉴입니다. 사용자가 늘수록 문서에서 찾은 오류를 보고하거나, 노드의 사용 경험을 공유하거나, 직접 확장한 내용을 공개하고 싶어질 수 있습니다.
처음 배우는 단계에서는 우선순위가 높지 않습니다. 하지만 n8n은 커뮤니티 노드와 템플릿, 포럼의 도움을 받으며 성장한 도구이기도 합니다. 공식 문서에서 해결되지 않는 문제를 만났을 때 어떤 경로로 피드백하고 도움을 구할 수 있는지 알아두면 좋습니다.
Contribute/
├─ Contribution guide for n8n Docs (문서 기여 가이드)
├─ Style guide for n8n Docs (문서 작성 스타일 가이드)
├─ Terminology (용어 정리)
└─ Where to get help (도움 받을 곳)
문서를 읽는 순서보다, 만들어 보는 순서가 중요합니다
처음 n8n을 공부한다면 이 흐름을 추천합니다.
Get started에서 Cloud·로컬·셀프호스팅 중 한 가지 시작 방식을 고릅니다.Build your first workflow를 따라 작은 워크플로우를 끝까지 실행합니다.- 용어가 막히면
Key concept glossary에서 필요한 단어만 확인합니다. - Google Sheets, Slack, Notion처럼 내 업무에 가까운 노드를 하나 골라
Nodes에서 설정을 봅니다. - 인증에서 막히면
Connect로 돌아가고 실행이 늘면Deploy와Administer를 읽습니다.
작은 연습 과제는 다음 정도면 충분합니다.
- Google Form 응답 → Google Sheets 저장 → Slack 알림
- Schedule Trigger → RSS 수집 → 요약 → Notion 저장
- Webhook 수신 → 조건 분기 → 담당자 알림
이 세 흐름을 만들면 Trigger, 데이터 전달, 인증, 조건 분기, 외부 서비스 연결, 실행 기록을 한 번씩 겪게 됩니다.
한국어로 이해하고, 영어 키워드로 찾으면 됩니다
n8n 공식 문서는 영어 중심입니다. 페이지 전체를 번역해 읽기보다, 질문은 한국어로 정리하고 검색과 설정은 원문 용어를 유지하는 방식이 효율적입니다.
Webhook, Trigger, Credentials, Expression, Execution, HTTP Request, IF, Switch 같은 이름은 번역하지 말고 그대로 검색하세요. API 필드명, 환경 변수, 코드, Expression, UI 옵션도 원문을 유지해야 설정 오류를 줄일 수 있습니다.
문서에서 막히면 먼저 실행 기록을 엽니다. 실패한 노드와 입력·출력을 확인한 다음 오류 문구를 그대로 검색합니다. AI 검색 도구를 쓰더라도 인증·보안·환경 변수·배포 방식은 반드시 원문 문서를 다시 확인하는 습관이 좋습니다.
n8n Docs는 한 번에 완독할 매뉴얼이 아닙니다. 작동하는 자동화를 하나 만들고 막힌 지점에서 정확한 문서로 돌아오는 길잡이에 가깝습니다.