---
id: custom-node-registry
title: "Custom Node Registry"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["Node Catalog", "Node Schema Registry"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.85
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/models/LLM/", "ComfyUI/custom_nodes/ComfyUI-WorkflowGenerator", "/object_info endpoint", "/workflow/convert endpoint"]
github_commit: ""
---

# [[Custom Node Registry]]

## 🎯 한 줄 통찰 (One-line insight)
Custom Node Registry는 ComfyUI의 유연한 확장성을 지탱하는 핵심 데이터베이스로, JSON 워크플로의 추상화된 노드 타입을 실제 Python 실행 로직 및 스키마와 연결하는 권위 있는 원천이다. [1-3]

## 🧠 핵심 개념 (Core concepts)
- **Node Mapping (class_type):** 워크플로 JSON 내의 `type` 또는 `class_type` 문자열을 로컬 환경에 설치된 실제 Python 클래스 기능과 매핑한다. [2, 4, 5]
- **Schema Discovery (object_info):** 실행 중인 ComfyUI 인스턴스에서 모든 노드의 입력/출력 유형, 필수 여부, 허용 범위를 동적으로 카탈로그화하여 제공한다. [3, 6]
- **Dependency Tracking:** 외부에서 유입된 JSON 워크플로를 로컬 레지스트리와 대조하여 누락된 커스텀 노드 패키지를 식별하고 관리한다. [7, 8]
- **Semantic Validation:** 자연어 기반 워크플로 생성 시, 생성된 노드 이름이 실제 로컬 레지스트리에 존재하는지 검증하고 교정하는 기준점이 된다. [9-11]

## 🧩 추출된 패턴 (Extracted patterns)
- **Scan-and-Catalog 패턴:** 새로운 커스텀 노드를 설치하거나 업데이트한 후 `UpdateNodeCatalog` 노드 등을 실행하여 로컬 노드 환경을 최신화하고 카탈로그 파일을 생성한다. [11-13]
- **Runtime Resolution 패턴:** 백엔드 엔진은 실행 시점에 JSON의 `class_type`을 레지스트리에서 찾아 기능을 호출하며, 시각적 데이터가 제거된 API 포맷에서 이 매핑이 특히 중요하다. [2, 5, 14]
- **Schema Inversion 패턴:** `/object_info` 엔드포인트를 통해 레지스트리를 외부로 노출함으로써, 외부 앱이 ComfyUI 내부 로직을 모르더라도 노드 인터페이스를 동적으로 구성할 수 있게 한다. [3, 15]

## 📖 세부 내용 (Details)
Custom Node Registry는 ComfyUI 워크플로 생성 및 직렬화의 근간을 이룬다. 워크플로가 JSON으로 저장될 때, 각 노드는 레지스트리에 등록된 고유한 **class_type**을 기반으로 식별된다. [2, 4] 이는 프론트엔드에서 사용하는 시각적 ID와는 별개의 기능적 키 값이다. [2, 16]

**주요 구성 요소 및 역할:**
1. **스키마 정의 (object_info.json):** 이 레지스트리는 각 노드가 요구하는 `required` 및 `optional` 입력값, 데이터 타입, 도구 설명(tooltips) 등을 상세히 포함한다. [3] 개발자는 이를 활용해 입력값을 검증하거나 동적으로 워크플로 수정 도구를 빌드할 수 있다. [3, 15, 17]
2. **의존성 해결 및 관리:** ComfyUI Manager는 외부에서 로드된 JSON의 노드 클래스를 로컬 레지스트리와 교차 검증한다. [7] 일치하는 항목이 없을 경우 "Missing Custom Node" 에러(빨간색 박스)를 발생시키고, 레지스트리 정보를 바탕으로 자동 설치를 지원한다. [7, 18]
3. **API 변환 및 검증:** `Workflow to API Converter`와 같은 도구는 정확한 변환을 위해 ComfyUI의 실제 노드 레지스트리를 직접 참조하여 리스트, 딕셔너리 위젯, 서브그래프 등을 처리한다. [19]
4. **LLM 기반 생성의 준거 집단:** 자연어 설명을 워크플로로 변환하는 시스템(`ComfyUI-WorkflowGenerator`)은 레지스트리 데이터를 기반으로 학습되거나, 생성 단계에서 레지스트리와의 시맨틱 매칭을 통해 유효한 그래프 구조를 보장한다. [9, 10, 20]

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **정적 모델과 동적 레지스트리의 간극:** 고정된 데이터로 학습된 LLM 모델은 학습 시점 이후에 출시된 새로운 커스텀 노드를 레지스트리에서 인식하지 못하는 한계가 있으며, 이를 극복하기 위해 실시간 카탈로그 스캔이 필수적이다. [21-23]
- **버전 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해 노드 레지스트리 내의 클래스 이름이나 구조가 변경될 수 있으며, 이로 인해 과거 버전의 JSON 파일이 최신 레지스트리에서 제대로 작동하지 않을 수 있다. [24]

## 🛠️ 적용 사례 (Applied in summary)
- **UpdateNodeCatalog:** 사용자가 설치한 모든 네이티브 및 커스텀 노드를 스캔하여 로컬 카탈로그를 갱신하는 기능이 구현되어 있다. [11, 12]
- **ComfyUI Manager:** JSON 내의 `class_type`을 파싱하여 레지스트리에 없는 패키지를 탐지하고 설치 인터페이스를 제공한다. [7, 8]
- **Workflow to API Converter Endpoint:** 클라이언트 측 JS 로직을 Python으로 변환하여 서버 사이드에서 노드 레지스트리를 참조해 비-API 포맷을 API 포맷으로 변환한다. [19, 25]
- **object_info 엔드포인트:** `/object_info` 경로를 통해 현재 인스턴스의 전체 노드 스키마 레지스트리를 JSON 형태로 배포한다. [15]

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 적용 사례가 소스 코드 및 공식 문서 내 엔드포인트 형태로 다수 발견됨) [7, 15, 19]
- **출처 신뢰도:** B (Official Documentation / GitHub Repository README / API Docs 기반)
- **중복 검사 결과:** 신규 생성 (New discovery)


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

### 상위/유사 개념
#### [아키텍처/기반 기술]
- [[Workflow API JSON (Backend Format)]]
  - 연결 이유: API 포맷은 시각적 메타데이터 없이 오직 레지스트리의 기능적 키에만 의존하여 실행된다. [2, 26]
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 데이터가 백엔드 실행 로직으로 변환되는 방식. [2, 5]
- [[JSON Schema v1.0]]
  - 연결 이유: 레지스트리에 정의된 노드 객체들이 준수해야 할 구조적 제약 조건을 정의한다. [4]
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 ID, 타입, 위젯 값 등의 기술적 사양. [4, 27]

#### [구현/활용 도구]
- [[ComfyUI Manager]]
  - 연결 이유: 레지스트리 불일치 문제를 해결하고 의존성을 관리하는 가장 보편적인 도구이다. [7, 18]
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 누락된 노드 설치 및 패키지 관리 프로세스. [7, 28]
- [[ComfyUI-WorkflowGenerator]]
  - 연결 이유: 자연어를 레지스트리에 존재하는 유효한 노드 그래프로 변환하는 파이프라인을 제공한다. [10, 29]
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 레지스트리 데이터를 활용한 AI 기반 자동화 방법론. [9, 20, 30]

### 심층 후속 질문 (Deeper Research Questions)
- 서로 다른 커스텀 노드 패키지 간에 클래스 이름(`class_type`)이 충돌할 경우 레지스트리는 어떤 우선순위로 이를 처리하는가?
- 수백 개의 커스텀 노드가 설치된 환경에서 동적 카탈로그 스캔(`UpdateNodeCatalog`)이 시스템 성능 및 로딩 시간에 미치는 영향은 무엇인가?
- `object_info.json`의 스키마 데이터를 활용하여 외부 웹 대시보드에서 실시간으로 ComfyUI 노드 UI를 완벽하게 재현할 수 있는가?
- 노드 레지스트리의 변경 사항(필드 추가/삭제)이 기존에 직렬화된 JSON 워크플로의 하위 호환성에 미치는 영향과 그 대응 전략은 무엇인가?
- `.cpack.zip`과 같은 워크스페이스 패키징 방식은 레지스트리 의존성 문제를 어떻게 영구적으로 해결하는가? [31]

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** 외부 애플리케이션 개발 시 `/object_info`를 호출하여 사용자 입력값이 노드 레지스트리 규격에 맞는지 클라이언트 사이드에서 즉시 검증할 수 있다. [3, 15]
- **System Design:** Python 스크립트에서 워크플로를 동적으로 생성할 때 노드 ID 대신 레지스트리의 타이틀이나 클래스 명을 참조하는 래퍼 라이브러리를 사용하여 유지보수성을 높일 수 있다. [32]
- **Operation / Maintenance:** 워크플로 공유 시 `Workflow to API Converter (Marker)` 노드를 추가하여 타인이나 매니저가 레지스트리 의존성을 쉽게 식별하도록 돕는다. [8]
- **Learning Path:** 노드 메뉴얼을 읽는 대신 `object_info` 데이터를 분석하여 특정 노드의 모든 가능한 입력 조합과 데이터 흐름을 기술적으로 파악할 수 있다. [3]

### 인접 주변 주제 (Adjacent Topics)
- [[Execution Model Inversion]]
  - 확장 방향: 레지스트리의 전체 노드 중 최종 출력에 필요한 노드만 선택적으로 실행하는 백엔드 최적화 원리. [33]
- [[Model Hashing]]
  - 확장 방향: 노드 정의 외에도 레지스트리에서 참조하는 모델 파일의 일관성을 보장하는 기술. [34]

## 📝 변경 이력 (Change history)
- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. [Source 26, 28, 37, 41, 133, 151 기반 합성]