---
id: custom-nodes
title: "Custom Nodes"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["커스텀 노드", "확장 노드"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.90
created_at: 2026-05-19
updated_at: 2026-05-19
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["ComfyUI/custom_nodes", "GitHub: DanielPFlorian/ComfyUI-WorkflowGenerator", "GitHub: SethRobinson/comfyui-workflow-to-api-converter-endpoint", "GitHub: pydn/ComfyUI-to-Python-Extension"]
github_commit: "bc85382"
---

# [[Custom Nodes]]

## 🎯 한 줄 통찰 (One-line insight)
커스텀 노드는 ComfyUI의 모듈형 아키텍처를 무한히 확장하는 핵심 동력이지만, 워크플로우 JSON의 이식성과 실행 가능성을 결정짓는 가장 큰 종속성 변수이다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **생태계 확장성 (Ecosystem Extensibility):** 기본 노드 세트(Core nodes) 외에 전 세계 개발자들이 공유하는 기능을 추가하여 Stable Diffusion뿐만 아니라 비디오, 오디오, 3D 생성 등 모든 유형의 미디어 자산을 생성할 수 있게 한다 [2, 3].
- **클래스 타입 매핑 (Class_type Mapping):** JSON 워크플로우 파일 내에서 각 노드는 `class_type` 속성을 통해 식별되며, 실행 시 로컬의 커스텀 노드 레지스트리와 대조된다 [4, 5].
- **종속성 관리 (Dependency Management):** 외부 워크플로우를 불러올 때 해당 시스템에 특정 커스텀 노드가 없으면 'Red Boxes' 에러가 발생하며, 이를 해결하기 위해 ComfyUI Manager와 같은 도구가 필수적이다 [5, 6].

## 🧩 추출된 패턴 (Extracted patterns)
- **누락 노드 복구 패턴:** 외부 JSON 로드 시 발생하는 'Red Boxes'를 감지하고 ComfyUI Manager를 통해 "Install Missing Custom Nodes"를 실행하여 서버를 재시작하는 복구 흐름이 정형화되어 있다 [5, 6].
- **마커 노드 활용 패턴:** 워크플로우 공유 시 ComfyUI Manager가 종속성을 더 쉽게 감지할 수 있도록 "Workflow to API Converter (Marker)"와 같은 특정 마커 노드를 의도적으로 포함시킨다 [7].
- **LLM 기반 자동 검색 패턴:** `Update Node Catalog` 노드를 사용하여 현재 설치된 모든 커스텀 노드를 스캔하고, 이를 LLM이 자연어를 JSON으로 변환할 때 참조하는 데이터베이스로 활용한다 [8, 9].

## 📖 세부 내용 (Details)
커스텀 노드는 ComfyUI의 `custom_nodes` 디렉토리에 설치되며, 주로 Git 클론을 통해 추가된다 [10, 11]. 워크플로우 JSON 생성 시, 커스텀 노드의 정보는 다음과 같이 처리된다.

- **JSON 내 기록:** 워크플로우가 저장될 때 각 커스텀 노드의 설정, 위젯 값, 연결 관계가 JSON의 `nodes` 배열에 포함된다 [12, 13]. API 포맷인 경우 비주얼 메타데이터가 삭제된 `class_type`과 `inputs` 정보만 남는다 [4, 14].
- **주요 커스텀 노드 예시:** 
    - **ComfyUI-Manager:** 노드 및 모델 설치/관리의 중추 [10].
    - **Efficiency Nodes:** 여러 노드를 하나로 결합하여 워크플로우를 간소화함 [15, 16].
    - **AnimateDiff Evolved & VideoHelperSuite:** 비디오 생성을 위한 필수 확장 [15, 16].
    - **IPAdapter Plus & ControlNet Aux:** 정밀한 이미지 제어를 위한 노드군 [16, 17].
- **개발자 도구와의 통합:** `Comfy Nodekit`과 같은 Python 라이브러리는 서버의 커스텀 노드 레지스트리와 자동으로 동기화되어, 프로그래밍 방식으로 워크플로우를 생성할 때 타입 안정성을 제공한다 [18]. 또한 `ComfyUI-to-Python-Extension`은 이러한 커스텀 노드가 포함된 그래프를 순수 Python 스크립트로 변환하여 독립 실행을 지원한다 [19].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **버전 호환성 문제:** ComfyUI가 빈번하게 업데이트됨에 따라, 과거에 생성된 JSON 파일 내의 커스텀 노드 구성이 최신 버전의 노드와 충돌하여 제대로 작동하지 않을 수 있다는 경고가 존재한다 [20, 21].
- **데이터 증발 위험:** 일반적인 이미지 편집기나 소셜 미디어 플랫폼에서 이미지를 처리할 때, 커스텀 노드 정보가 담긴 메타데이터(JSON)가 삭제될 수 있어 전용 추출 도구 사용이 권장된다 [22, 23].

## 🛠️ 적용 사례 (Applied in summary)
- **설치 위치:** `ComfyUI/custom_nodes` 디렉토리 하위에 각 노드 패키지가 배치됨 [10, 11].
- **GitHub 프로젝트:** 
    - `DanielPFlorian/ComfyUI-WorkflowGenerator`: LLM을 통해 커스텀 노드를 포함한 워크플로우를 자동 생성하는 노드 구현 [24, 25].
    - `SethRobinson/comfyui-workflow-to-api-converter-endpoint`: (커밋 `bc85382`) 비 API 포맷의 커스텀 노드 워크플로우를 API 포맷으로 변환하는 서버 사이드 로직 구현 [26, 27].
- **의사결정 기록:** ComfyUI Manager의 "Install Missing Custom Nodes" 기능은 커스텀 노드 부재로 인한 워크플로우 실행 실패를 해결하는 표준 운영 절차(SOP)로 확립됨 [5, 6].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (다수의 GitHub 프로젝트 및 공식 튜토리얼을 통해 실무 적용 확인됨)
- **출처 신뢰도:** B (공식 문서 및 주요 개발자 리포지토리 기반)
- **중복 검사 결과:** 신규 생성

## 🔗 관련 문서 링크 (Related document links)

### 상위/유사 개념
#### [아키텍처 및 기반 기술]
- [[Comfyui workflow json 생성 방법]]
  - 연결 이유: 커스텀 노드는 JSON 파일의 내용을 구성하는 가장 동적인 요소임.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내 `class_type`이 어떻게 실제 기능으로 매핑되는지 이해 가능.
- [[Workflow API JSON]]
  - 연결 이유: API 실행 시 커스텀 노드의 입출력 구조가 이 포맷에 맞춰 최적화됨.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: UI 없는 환경에서의 커스텀 노드 호출 메커니즘.

#### [구현 및 관리 도구]
- [[ComfyUI Manager]]
  - 연결 이유: 커스텀 노드의 설치, 업데이트, 누락 복구를 담당하는 전용 도구임.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 복잡한 종속성 문제를 자동화하는 방법.

### 심층 후속 질문 (Deeper Research Questions)
- 커스텀 노드의 `class_type`이 중복될 경우 ComfyUI는 어떤 우선순위로 노드를 로드하는가?
- `Update Node Catalog` 노드는 어떤 방식으로 로컬에 설치되지 않은 원격 커스텀 노드의 정보를 수집할 수 있는가? [9]
- 커스텀 노드 내에서 정의된 `INPUT_TYPES`가 JSON Schema v1.0 규격과 충돌할 때 발생하는 예외 처리 메커니즘은 무엇인가? [28]
- `comfy-pack`과 같은 도구에서 모델 해싱(SHA-256)을 사용할 때 커스텀 노드 내부의 모델 경로 의존성은 어떻게 해결되는가? [29]
- LLM 기반 워크플로우 생성기에서 학습 데이터에 없는 최신 커스텀 노드를 인식시키기 위한 RAG(Retrieval-Augmented Generation) 적용 방안은 무엇인가? [30]

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** 새로운 기능을 개발할 때 `ComfyUI/custom_nodes`에 Python 클래스를 정의하고 이를 JSON에서 호출 가능한 형태로 등록함 [3, 10].
- **System Design:** API 서버 구축 시 모든 필요한 커스텀 노드가 사전 설치된 Docker 이미지를 준비해야 함 [31].
- **Operation / Maintenance:** 워크플로우 공유 시 "Red Box" 발생을 최소화하기 위해 필수 커스텀 노드 목록을 별도로 제공하거나 마커 노드를 포함함 [6, 7].
- **Learning Path:** 기본 워크플로우 숙지 후, `Efficiency Nodes`나 `Manager` 설치를 통해 고급 워크플로우 설계 단계로 진입함 [15, 32].

### 인접 주변 주제 (Adjacent Topics)
- [[Model Hashing]]
  - 확장 방향: 커스텀 노드가 사용하는 특정 모델 파일의 이름 불일치 문제를 해결하는 보완 기술 [29].

## 📝 변경 이력 (Change history)
- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source identifiers: [1, 3, 5, 6, 10, 19, 25, 26])