가이드

작성자 Matt Connor 2026-07-15 · 업데이트됨 2026-07-24

n8n에서 Claude API 연결하여 AI 워크플로우 구축하기

VPS 환경의 n8n에 Claude를 연결하는 통합 가이드입니다. API Key 설정법부터 모델별 노드 선택, 3가지 실전 워크플로우, 그리고 실행 시 발생하는 비용 계산법과 주의사항을 상세히 다룹니다.

구축하게 될 내용

이미 실행 중인 n8n 인스턴스에서 작동하는 세 가지 AI 워크플로우를 구축합니다. 입력된 내용을 요약하는 webhook, 기사를 구조화된 스프레드시트 행으로 변환하는 스케줄링된 피드 리더, 그리고 질문에 답하기 위해 스스로 HTTP API를 호출하는 AI Agent입니다. 이는 VPS에서 Python으로 Claude API를 호출하는 방법에 대한 no-code 방식의 대응책입니다. 동일한 API, 동일한 토큰, 동일한 비용이 발생하지만, 오케스트레이션이 스크립트 대신 n8n 노드에서 수행됩니다.

Docker를 이용한 self-hosted n8n 가이드에 따라 n8n이 이미 HTTPS 환경에서 실행 중이라고 가정합니다. 그렇지 않다면 먼저 이를 완료하십시오. webhook에는 실제 TLS 엔드포인트가 필요하며, API key를 저장할 credential store에는 해당 가이드에서 강조하는 encryption-key 백업이 필요합니다.

여기서 중요한 문제는 drag-and-drop 기능이 아닙니다. 노드별 모델 선택, undefined를 암묵적으로 보간하는 프롬프트 필드, 그리고 자동화가 무인 상태로 실행된다는 점입니다. 실행당 0.5센트가 드는 워크플로우라도 재시도 루프가 밤새 4,000번 실행되면 비용이 급증합니다. 이 가이드의 대부분은 이러한 주제를 다룹니다.

백업한 키로 암호화된 단일 credential

platform.claude.com의 Anthropic Console에서 API key를 가져오십시오. Settings, 그 다음 API Keys로 이동하여 n8n-vps와 같은 이름으로 키를 생성합니다. 키는 한 번만 표시됩니다. 계정에 금액을 충전하거나 결제 수단을 설정하십시오. API 사용량은 사용한 토큰만큼 비용이 발생하는 pay-per-token 방식이며 Claude.ai 구독과는 완전히 별개입니다.

n8n 설정: Credentials, Create credential, Anthropic을 선택하고, API Key 필드에 키를 붙여넣은 후 저장합니다. 모든 워크플로우의 모든 Claude 노드는 이 저장된 credential을 참조합니다. 노드에 키를 직접 붙여넣지 마십시오.

두 가지 운영 주의사항이 있습니다. 첫째, n8n은 저장된 credential을 N8N_ENCRYPTION_KEY로 암호화합니다. n8n 가이드에 따라 compose 파일에 해당 env var를 명시적으로 설정하면 컨테이너를 재빌드해도 credential이 유지됩니다. 만약 n8n이 생성한 키를 사용하다가 volume을 분실하면, 이 키를 포함한 모든 저장된 credential은 복구 불가능한 ciphertext가 됩니다. 이 단계를 건너뛰었다면 지금 키를 백업하십시오. 둘째, n8n credential store를 blast radius(영향 범위)로 간주하십시오. 인스턴스에서 워크플로우를 편집할 수 있는 사람은 누구나 귀하의 Anthropic 키로 요청을 보낼 수 있습니다. 인스턴스가 해킹되거나 통제 불능 상태가 될 경우를 대비해 Console의 Settings에서 지출 한도(spend limit)를 설정하십시오.

모델 선택은 노드별 결정 사항입니다

n8n의 Claude 노드에 있는 모델 드롭다운은 API에서 실시간으로 정보를 가져오므로, 귀하의 키가 접근 가능한 모델을 보여줍니다. 2026년 7월 기준, 입력/출력 토큰 100만 개당 모델 라인업 및 API 가격은 다음과 같습니다: Claude Haiku 4.5 (claude-haiku-4-5)는 $1/$5 (context window 200K), Claude Sonnet 5 (claude-sonnet-5)는 $3/$15 (2026년 8월 31일까지 한시적 도입가 $2/$10), Claude Opus 4.8 (claude-opus-4-8)은 $5/$25이며, 두 모델 모두 1M-token context window를 제공합니다. 또한 가장 어려운 추론 작업을 위한 Claude Fable 5 (claude-fable-5)가 $10/$50에 제공되지만, 이 가이드의 어떤 내용도 이를 필요로 하지 않습니다. 정확한 ID를 사용하십시오. 오래된 튜토리얼에서 본 날짜 접미사가 붙은 변형 모델을 사용하면 404 오류가 발생합니다. 또한 가격은 변동될 수 있으므로, 이곳을 포함하여 어디서 읽은 숫자든 신뢰하기 전에 platform.claude.com을 확인하십시오.

습관화해야 할 점은 플랫폼 단위가 아닌 노드 단위로 모델을 선택하는 것입니다. 분류, 추출, 요약, 라우팅과 같은 자동화의 핵심 작업은 Sonnet의 기본 가격의 1/3인 Haiku에서 매우 효율적으로 작동하며, Opus의 1/5 가격으로 실행됩니다. Sonnet은 에이전트와 다단계 추론에 사용하고, Opus는 잘못된 답변으로 인한 비용이 토큰 비용보다 더 큰 드문 경우에만 사용하십시오. 5개의 Claude 노드를 가진 워크플로우는 모델을 혼합하여 사용할 수 있으며, 그래야만 합니다.

두 가지 Claude 노드와 용도별 선택 방법

n8n에는 두 가지 별개의 Anthropic 통합 기능이 포함되어 있으며, 잘못된 것을 선택하는 것이 초보자가 가장 자주 겪는 시행착오입니다.

Anthropic 노드는 일반적인 app 노드입니다. 하나의 요청이 들어가면 하나의 응답이 나옵니다. Text 리소스에는 Message a Model 작업이 있으며, 이미지 및 문서를 분석하는 작업도 포함됩니다. 트리거, Claude 호출, 다음 노드로 이어지는 워크플로우 로직이 n8n에 있는 경우 이 노드를 사용하십시오. 아래의 워크플로우 1과 2는 이 노드 또는 그에 상응하는 체인을 사용합니다.

Anthropic Chat Model 노드는 sub-node입니다. AI Agent 또는 Basic LLM Chain과 같은 루트 노드에 모델을 공급하는 작은 부속 노드입니다. 자체적인 트리거나 출력이 없습니다. 대신 모델 선택기 및 Maximum Number of Tokens, Sampling Temperature와 같은 샘플링 옵션을 제공합니다. n8n 문서에서 반드시 기억해야 할 주의사항이 있습니다. sub-node 내부의 expression은 각 아이템이 아니라 첫 번째 입력 아이템을 기준으로 항상 resolve됩니다. 따라서 아이템별 expression은 sub-node가 아닌 루트 노드의 프롬프트 필드에 작성하십시오.

Workflow 1: webhook 입력, 요약 출력

AI 자동화의 Hello-world입니다. URL로 POST된 모든 내용은 요약되어 Slack이나 이메일로 전송됩니다.

Webhook 노드 — HTTP Method POST, path summarize. n8n은 test URL과 production URL을 제공합니다. production URL은 워크플로우가 활성화된 후에만 작동합니다.
Anthropic 노드 — Message a Model, model claude-haiku-4-5, Max Tokens 약 300.
Slack 노드 (또는 Send Email) — 응답 텍스트를 채널에 게시합니다.

프롬프트는 n8n expression과 Claude가 만나는 지점입니다. POST body는 $json.body 아래에 위치하므로, user message 필드는 다음과 같습니다:

Summarize the following feedback in three bullets, then one line:
verdict: praise | complaint | churn-risk. No preamble.

{{ $json.body.text }}

역할 및 형식 지침은 노드의 system prompt 필드에 작성하십시오. payload가 변하더라도 system prompt는 일정하게 유지되어 동작을 안정화하고 6개월 후에도 프롬프트를 읽기 쉽게 만듭니다. VPS 자체에서 다음을 테스트하십시오:

curl -X POST https://n8n.example.com/webhook/summarize \
  -H 'Content-Type: application/json' \
  -d '{"text": "Third support ticket this month about slow disk IO..."}'

Haiku 기준 실행당 비용: 1,200-token payload와 프롬프트는 입력에 약 $0.0012, 300-token 출력은 $0.0015가 소요됩니다. 즉, 실행당 약 0.25센트입니다. 한 달에 1,000번 실행해도 $3 미만입니다. 동일한 노드를 Opus 4.8에 연결하면 비용이 약 5배 증가합니다. 이 비율이 모든 워크플로우에 적용될 때 노드별 모델 선택 습관이 중요한 이유입니다.

Workflow 2: 스케줄링된 RSS를 구조화된 행으로 변환

이제 정해진 시간에 구조화된 출력을 생성하는 작업을 수행합니다. 매시간 RSS 피드를 읽고, 각 항목을 분류하여 시트에 행을 추가합니다.

Schedule Trigger — 매시간 실행.
RSS Read — 피드 URL. 기사당 하나의 아이템을 출력합니다.
Basic LLM Chain — claude-haiku-4-5로 설정된 Anthropic Chat Model sub-node와 JSON schema를 가진 Structured Output Parser sub-node를 포함합니다.
Google Sheets (또는 Postgres) — 아이템당 하나의 행을 추가합니다.

Structured Output Parser는 "Claude, JSON으로 반환해줘"라는 희망 사항을 계약으로 바꿔줍니다. 모델의 응답을 schema와 대조하여 검증하며, 쓰레기 데이터를 행으로 쓰는 대신 해당 아이템을 명확히 실패 처리합니다. schema 예시는 다음과 같습니다:

{
  "type": "object",
  "properties": {
    "category": { "type": "string", "enum": ["release", "security", "tutorial", "other"] },
    "relevance": { "type": "number" },
    "one_line_summary": { "type": "string" }
  },
  "required": ["category", "relevance", "one_line_summary"]
}

그리고 체인의 프롬프트는 피드 아이템을 참조합니다:

Classify this article for a VPS hosting audience.

Title: {{ $json.title }}
Content: {{ $json.contentSnippet }}

여기서 비용 계산 방식이 달라집니다. 이는 실행당 비용이 아니라 아이템당 비용입니다. 매시간 50개의 기사가 24시간 동안 처리되면 한 달에 36,000번의 Claude 호출이 발생합니다. Haiku의 경우 기사 길이에 따라 약 $40–$90가 소요되며, Opus는 그 5배 정도입니다. LLM 노드 이전에 중복을 제거하십시오(이전에 본 링크와 비교하는 간단한 IF 문 또는 n8n의 Remove Duplicates 노드 사용). 대부분의 시간당 폴링에는 새로운 내용이 없으므로 중복을 제거하면 호출 횟수가 급감합니다. 가장 저렴한 토큰은 호출하지 않은 호출입니다.

Workflow 3: 도구를 사용하는 AI Agent

처음 두 워크플로우는 파이프라인입니다. 사용자가 단계를 결정합니다. AI Agent 노드는 이를 반전시킵니다. Claude에게 목표와 도구를 주면, Claude가 완료될 때까지 어떤 도구를 어떤 순서로 호출할지 스스로 결정합니다. n8n에서는 chat model sub-node와 최소 하나 이상의 tool sub-node가 연결되어야 합니다.

구체적인 예시 — 모니터링 시스템으로부터 "무엇이 다운되었고 왜 그런가"라는 질문에 답하는 운영 어시스턴트:

Chat Trigger (또는 webhook) — 질문이 들어옵니다.
AI Agent — claude-sonnet-5로 설정된 Anthropic Chat Model sub-node를 포함합니다. Agent는 도구 호출을 계획하고 체인화합니다. Haiku는 단순한 단일 도구 에이전트를 구동할 수 있지만, 도구가 늘어나면 Sonnet이 적절한 최소 사양입니다.
HTTP Request 노드를 도구로서 연결 — Uptime Kuma status API 또는 Zabbix 엔드포인트를 가리킵니다. 두 번째 HTTP 도구는 REST API가 있는 다른 무엇이든 호출할 수 있습니다.

두 가지 설정이 대부분의 작업을 수행합니다. 에이전트의 System Message는 직무를 정의합니다: "당신은 운영 어시스턴트입니다. 답변하기 전에 status 도구를 사용하여 현재 모니터 상태를 확인하십시오. 다운된 모니터와 지속 시간만 보고하십시오." 또한 각 도구의 description은 사람을 위한 문서가 아닙니다. Claude가 언제 도구를 호출할지 결정하는 기준입니다. "모든 모니터링 서비스의 현재 up/down 상태를 JSON으로 반환"이라고 작성하면 적절한 순간에 호출되지만, "status API"라고 작성하면 무시되거나 잘못 사용됩니다. HTTP Request 노드를 도구로 연결할 때 Optimize Response 옵션을 활성화하고 중요한 JSON 필드만 선택하십시오. 그렇지 않으면 모든 상세한 API 응답이 입력 토큰으로 모델의 컨텍스트에 들어가 비용이 발생합니다.

에이전트의 Max Iterations를 작동하는 최소한의 숫자로 설정하십시오(기본값은 10입니다). 이는 "에이전트가 도구 4번 호출 후 포기함"과 "수십 번의 모델 왕복 루프" 사이의 차이를 만듭니다. 또한 과금 구조를 이해하십시오. 각 iteration은 지금까지의 전체 대화(system message, 질문, 모든 이전 도구 결과)를 입력 토큰으로 다시 전송합니다. 6번의 iteration을 거친 에이전트 실행은 누적 입력 토큰 20,000개와 출력 2,000개에 쉽게 도달할 수 있습니다. Sonnet 5의 도입가 기준 약 $0.06, 표준 가격($3/$15) 기준 약 $0.09가 소요됩니다. 이는 단순 요약 실행을 20번 수행하는 것과 같습니다. 하나의 에이전트에 너무 많은 도구를 붙이고 있다면, VPS에서 MCP 서버를 실행하는 것이 더 깔끔한 아키텍처가 되는 시점입니다.

비용 방어선, 아무도 지켜보고 있지 않기 때문입니다

무인 워크플로우에는 사람이 키보드 앞에서 암묵적으로 제공하는 제어 장치가 필요합니다. 비용이 낮은 순서대로 4단계가 있습니다.

모든 Claude 노드에 Max Tokens 설정. 이는 엄격한 출력 제한입니다. 요약에는 300, 분류에는 100이 필요합니다. 이는 비용이 많이 드는 출력 측면($5–$25 per million output tokens vs $1–$5 for input)을 제한하며, runaway(폭주) 방지 장치 역할도 합니다. 프롬프트 버그로 Claude가 말을 길게 늘어놓더라도 8,000 토큰이 아닌 300 토큰만 소모됩니다.

노드별 모델 선택. 위에서 언급했듯이, 현재 라인업에서 5~10배의 가격 차이를 만드는 레버입니다. 설정하는 데 10초도 걸리지 않습니다.

루프 제한. 에이전트의 Max Iterations를 설정하십시오. 워크플로우 설정에서 workflow timeout을 설정하여 실행이 멈췄을 때 무한 루프에 빠지지 않고 종료되게 하십시오. 그리고 노드의 Retry On Fail 사용 시 주의하십시오. 일시적인 오류에는 적절한 도구이지만, 재시도는 비용을 배가시킵니다. Max Tries를 3으로 설정하고 Wait Between Tries를 5000 ms로 설정하면, 지속적인 오류 발생 시 아이템당 최대 3번까지 비용이 청구됩니다. 이미 비용이 많이 발생한 노드에 재시도 로직을 중첩하지 마십시오.

백업용 에러 워크플로우. Error Trigger 노드로 시작하여 실패한 워크플로우의 이름과 에러를 Slack에 게시하는 워크플로우를 생성한 후, 각 AI 워크플로우의 설정에서 이를 Error Workflow로 지정하십시오. 이 방식이 잡아내는 실패 모드는 매우 치명적입니다. 스케줄로 트리거된 워크플로우가 매시간, 일주일 내내 에러를 일으키며 실행될 때마다 토큰을 태우는 경우입니다. Anthropic Console에서 월간 지출 한도를 설정하고, 스케줄링된 작업을 활성화한 후 며칠 동안은 Console의 사용량 페이지를 확인하십시오. 정확한 청구 내역을 알고 싶다면 token-usage 가이드를 참조하십시오.

실패 모드와 나타날 증상들

"Authorization failed - please check your credentials"와 함께 노드가 즉시 실패함. API가 401을 반환했습니다. 실제 원인은 다음과 같습니다:

{"type": "error", "error": {"type": "authentication_error", "message": "invalid x-api-key"}}

키를 잘못 붙여넣었거나(잘림, 후행 공백), 튜토리얼의 플레이스홀더를 사용한 경우입니다. n8n credential을 다시 생성하고 다시 붙여넣으십시오. 어제 작동했다면 Console에서 키가 취소되었는지, 또는 volume 복구로 인해 다른 N8N_ENCRYPTION_KEY로 암호화된 credential로 되돌아갔는지 확인하십시오.

429 rate_limit_error 에러와 함께 실행이 폭발적으로 실패함. "Number of request tokens has exceeded your per-minute rate limit"와 같은 메시지가 나타납니다. Rate limit은 분당 단위이며, n8n은 50개의 webhook이나 RSS 실행을 동시에 발사하기 매우 쉽습니다. 구조적으로 해결하십시오. 병렬 대신 순차적으로 아이템을 처리(Loop Over Items)하고, Retry On Fail을 Max Tries 3, Wait Between Tries 5000 ms로 설정하십시오. n8n은 이 필드를 5000 ms로 제한합니다. 재시도가 다음 분(minute) 윈도우에 걸치도록 더 긴 대기 시간이 필요하다면, 에러 경로에 Wait 노드를 넣거나 아이템을 하나씩 처리하십시오. 응답 헤더에는 정확히 얼마나 기다려야 하는지 알려주는 retry-after 헤더가 포함되어 있습니다. n8n의 고정 대기 시간은 이를 읽을 수 없으므로, 긴 대기 시간은 직접 구현해야 합니다.

404 not_found_error 모델 이름 오류. 응답 본문에 오타가 표시됩니다:

{"type": "error", "error": {"type": "not_found_error", "message": "model: claude-haiku-4.5"}}

하이픈 대신 점을 사용하거나(4.5 대신 4-5), 오래된 블로그 포스트의 날짜 접미사, 또는 은퇴한 모델인 경우입니다. 현재 목록을 기준으로 ID를 수정하십시오. 모델 필드에 드롭다운 대신 expression을 입력하는 경우 이 문제가 자주 발생합니다.

Claude가 묻지 않은 질문에 답변함. 에러는 발생하지 않으며 실행 상태는 초록색(green)입니다. payload가 message인데 expression이 {{ $json.body.text }}와 같이 누락된 필드를 참조하면, 프롬프트에 undefined라는 문자열이 그대로 삽입되고 Claude는 아무 내용도 없는 프롬프트에 성실히 답변합니다. 참조된 노드가 아예 실행되지 않았다면 "Referenced node is unavailable"이 발생하지만, 필드가 누락된 경우는 조용히 넘어갑니다. 활성화하기 전에 항상 실제 데이터로 한 번 실행해 보고 노드의 input 패널에서 실제 렌더링된 프롬프트를 읽어보십시오. expression editor는 resolve된 값을 미리 보여주며, undefined를 통해 확인할 수 있습니다.

FAQ

Claude를 n8n에 어떻게 연결하나요?

Anthropic Console(platform.claude.com)에서 API key를 생성한 다음, n8n에서 Anthropic 타입의 credential을 추가하고 API Key 필드에 붙여넣으십시오. 모든 Claude 노드(Anthropic app 노드 및 Anthropic Chat Model sub-node)는 이 저장된 credential을 참조합니다. n8n은 이를 N8N_ENCRYPTION_KEY로 암호화하므로, 키를 백업하지 않으면 volume과 함께 credential을 잃게 됩니다.

AI 워크플로우의 실행당 비용은 얼마인가요?

실행당 예상 토큰 수를 계산한 뒤 모델의 100만 토큰당 가격을 곱하십시오. 2026년 7월 기준, Haiku 4.5는 입력/출력 토큰 100만 개당 $1/$5이며, Sonnet 5는 $3/$15(2026년 8월까지 도입가 $2/$10)입니다. Haiku를 이용한 webhook 요약은 약 0.25센트가 소요됩니다. 여러 도구를 사용하는 Sonnet 에이전트 실행은 매 iteration마다 전체 대화를 다시 전송하므로 $0.06–$0.10에 가깝습니다. 추정치 대신 Console의 사용량 페이지에서 확인하십시오.

n8n 자동화에는 어떤 Claude 모델을 사용해야 하나요?

분류, 추출, 요약, 라우팅과 같이 속도와 가격이 중요한 대량 작업에는 Haiku 4.5를 사용하십시오. AI Agent 노드와 다단계 추론에는 Sonnet 5를 사용하십시오. Opus 4.8은 잘못된 답변으로 인한 비용이 $5/$25의 가격을 정당화할 만큼 클 때만 사용하십시오(Haiku의 5배, Sonnet의 약 2배 미만). 모델은 워크플로우 단위가 아닌 노드 단위로 설정하십시오. 하나의 워크플로우에서 세 모델을 모두 혼합할 수 있습니다.

n8n 워크플로우가 Claude API 비용을 과다하게 지출하는 것을 어떻게 막나요?

방어선을 계층화하십시오. 모든 Claude 노드에 낮은 Max Tokens 설정, 에이전트의 Max Iterations 설정, 워크플로우 timeout 설정, 그리고 실패가 토큰 소모를 배가시키지 않도록 보수적인 Retry On Fail 설정을 적용하십시오. 그다음, AI 워크플로우가 실패할 때 Slack으로 알림을 보내는 Error Trigger 워크플로우를 추가하고, Anthropic Console에서 VPS가 넘을 수 없는 하드 한도인 월간 지출 한도를 설정하십시오.

AI Agent의 도구 호출(tool calls)에 추가 비용이 드나요?

별도의 도구 비용은 없지만, 도구는 공짜가 아닙니다. 모든 도구 결과는 입력 토큰으로서 모델에 다시 전달되며, 각 에이전트 iteration은 지금까지의 전체 대화를 다시 전송합니다. 필터링되지 않은 긴 API 응답은 실제 프롬프트보다 훨씬 큰 비용을 발생시킬 수 있습니다. HTTP Request 도구에서 Optimize Response를 활성화하고 에이전트에게 필요한 필드만 반환하도록 설정하십시오.

#n8n #claude #ai #automation#workflows