Claude로 깨진 ComfyUI 워크플로 복구하기
업데이트 후 멈춘 기존 ComfyUI 워크플로를 복구하는 실전 절차입니다. 원본 JSON과 로그를 보존하고, 기본 워크플로로 기준선을 확인한 다음, Claude가 실패 원인을 분류하게 하고, 복사본만 수정해 실제로 저장된 이미지로 결과를 검증합니다.
목차
처음부터 Claude에게 워크플로 전체를 다시 쓰라고 하지 마세요. 일반 Save 형식의 원본 JSON과 정확한 오류를 보관하고, custom nodes를 끈 상태에서 현재 기본 워크플로가 실행되는지 먼저 확인해야 합니다. 그다음 Claude에는 제공한 근거만 분류하게 하세요. 한 번에 하나의 의존성만 바꾸고, 가장 작은 실행 가능 그래프를 다시 만든 뒤 이미지 한 장을 실행해 Save Image에 결과가 나타나고 로컬에 저장해 다시 열 수 있는지 직접 확인합니다.
이 방식은 “ComfyUI가 많이 바뀌었다”는 모호한 문제를 ComfyUI core, frontend extension, custom node, model file, 기존 graph 자체라는 검증 가능한 층으로 나눕니다. 공식 ComfyUI 문제 해결 가이드도 수정 전에 기본 워크플로를 시험하고, custom nodes를 비활성화하며, 터미널의 정확한 오류를 확인하라고 안내합니다.
복구 순서 한눈에 보기
- 원본 워크플로를 일반 Save 형식으로 남기고 덮어쓰지 않습니다.
- 전체 오류, startup log, 설치 방식, 버전, 최근 변경 사항을 기록합니다.
- 모든 custom nodes를 끄고 현재 기본 이미지 워크플로를 실행합니다.
- Claude에는 범위를 제한한 근거 묶음만 주고, 편집이나 설치보다 분석을 먼저 시킵니다.
- 실패를 core, frontend, custom node, model, unknown으로 분류합니다.
- 호환되지 않는 노드 하나만 업데이트 또는 교체하거나 현재형 최소 그래프를 다시 만듭니다.
- 작은 이미지 한 장을 실행하고 실제 저장 파일을 검증합니다.
1. 변경 전에 워크플로와 근거를 고정하기
기존 워크플로를 일반 JSON으로 저장한 뒤 별도의 작업 복사본을 만드세요. 다음처럼 작은 조사 폴더에 모으면 과정을 재현하기 쉽습니다.
comfyui-repair-case/
workflow-original.json
workflow-working.json
error-report.txt
startup-log.txt
environment.mdworkflow-original.json은 읽기 전용으로 취급합니다. error-report.txt에는 “노드가 고장 났다”는 요약이 아니라 Show report의 전체 텍스트를 넣습니다. startup-log.txt에는 시작 터미널의 import failure, dependency conflict, traceback을 저장합니다. environment.md에는 Desktop, Portable, manual install 중 어떤 방식인지, ComfyUI 버전, 운영체제, GPU, 최근 core, frontend, custom nodes, models 중 무엇을 업데이트했는지 적습니다.
Save format과 API format도 구분해야 합니다. 공식 Workflow API Format에 따르면 일반 저장 형식은 노드 위치, 색상, 그룹 등 편집 메타데이터를 유지하지만, API 형식은 프로그램 제출을 위해 UI 메타데이터를 줄인 구조입니다. 복구 작업에는 일반 형식 원본을 보관하세요. API가 실제로 필요한 경우에만 별도의 API 복사본을 export합니다.
2. 기존 그래프보다 먼저 깨끗한 기준선 증명하기
기존 그래프를 첫 시험 대상으로 삼지 마세요. 서드파티 노드를 잠시 비활성화합니다. Desktop에서는 설정을 이용하고, manual install은 보통 다음처럼 시작할 수 있습니다.
python main.py --disable-all-custom-nodes현재 기본 Image Generation 템플릿을 불러오고, 모델 목록에 이미 보이는 호환 checkpoint를 선택해 이미지 한 장을 생성합니다. 공식 custom node 문제 해결 가이드는 명확한 분기를 제시합니다. custom nodes를 끄자 문제가 사라지면 custom node가 관련되며, 그대로라면 core, frontend, models, environment를 조사합니다.
결과에 따라 다음 경로를 고르세요.
| 기준선 결과 | 가능성이 높은 층 | 다음 검증 |
|---|---|---|
| 기본 워크플로도 열리거나 실행되지 않음 | Core 설치, frontend, model, hardware | 기존 graph를 건드리기 전에 기준선을 복구 |
| 기본은 되지만 기존 graph에 missing nodes 표시 | 누락, 이름 변경, 로드 실패한 custom nodes | JSON node type을 패키지 소유자와 매핑 |
| 기존 graph가 로드되나 특정 node에서 실패 | Model architecture, 연결, 의존성, 메모리 | 첫 실패 node와 전체 report 보관 |
| Frontend extensions를 끄자 UI가 정상화 | 호환되지 않는 서드파티 frontend extension | 절반씩 다시 켜며 하나를 격리 |
기본 그래프가 실패하는 상태에서는 기존 JSON을 다시 써도 복구 성공을 증명할 수 없습니다.
3. Claude에 경계를 둔 근거 묶음 제공하기
Anthropic은 Claude Code가 codebase를 읽고, 파일을 편집하고, 명령을 실행할 수 있다고 설명합니다. 강력한 기능이므로 첫 단계는 분석 전용이어야 합니다. 조사 폴더에서 Claude를 시작하거나 같은 파일을 채팅에 첨부하고 다음처럼 제한하세요.
업데이트 후 멈춘 ComfyUI 워크플로를 진단하세요.
다음 파일만 읽으세요.
- workflow-original.json
- workflow-working.json
- error-report.txt
- startup-log.txt
- environment.md
아직 어떤 것도 설치, 업데이트, 삭제, 이름 변경, 편집하지 마세요.
먼저 다음을 수행하세요.
1. Node type과 참조된 model file 목록을 만드세요.
2. 각 문제를 ComfyUI core, frontend extension,
custom node, model file, unknown으로 분류하세요.
3. 모든 결론에 정확한 JSON field 또는 error line을 인용하세요.
4. 되돌릴 수 있는 가장 작은 변경을 제안하세요.
5. workflow-working.json을 고치기 전에 승인을 기다리세요.
내가 이미지 한 장을 실행하고 저장 파일을 확인하기 전에는 성공했다고 말하지 마세요.좋은 답변은 기존 node type, 소유 extension, 입출력 계약, 대체 후보, parameter mapping, 근거, 위험을 정리한 표입니다. 소유자나 대체재를 확인할 수 없다면 비슷한 이름으로 추측하지 말고 unknown으로 표시해야 합니다.
4. 전부 업데이트하지 말고 실패 층을 분류하기
Missing node: 교체 전에 소유자 확인
일반 Save JSON에서 누락 노드의 type, title, link를 확인합니다. 이름이 비슷하다고 socket이나 widget values가 호환되는 것은 아니므로 JSON 문자열만 바꾸는 방식은 안전한 migration이 아닙니다. 해당 노드가 core인지 특정 custom-node repository인지 확인한 뒤 새 노드와 기존 노드의 입력, 출력, parameter를 비교합니다.
Extension이 유지보수 중이면 그 extension만 업데이트하고 다시 시험합니다. 중단되었다면 유지되는 대체재를 고르거나 core nodes로 해당 기능만 다시 만듭니다. 공식 가이드도 update, replace, author에게 report, remove/disable을 선택지로 제시합니다.
Frontend conflict: 비활성화 후 이분 탐색
일부 custom nodes는 frontend extensions도 주입합니다. 빈 화면, 끊어진 연결, 사라진 preview, frontend와 backend 통신 실패는 이 층에서 생길 수 있습니다. 먼저 서드파티 frontend extensions를 모두 끕니다. 증상이 사라지면 절반씩 켜며 재시험하세요. 이 binary search는 인과관계를 보존하며 전체 재설치보다 안전합니다.
Missing model: 폴더와 검색 경로 확인
기존 graph는 삭제, 이름 변경, 이동된 checkpoint, VAE, LoRA, ControlNet을 가리킬 수 있습니다. ComfyUI는 ComfyUI/models/ 아래 분류 폴더와 extra_model_paths.yaml의 경로에서 모델을 찾습니다. 선택 목록이 비어 있거나 null이면 실제 위치를 확인하고 refresh 또는 restart합니다. 기존 파일명과 맞추려고 호환되지 않는 모델 이름만 바꾸지 마세요.
Architecture mismatch: 파일명이 아니라 계열 확인
공식 모델 문제 해결 가이드는 워크플로 모델을 같은 architecture family 안에서 구성하라고 권합니다. 다른 계열의 checkpoint, VAE, text encoder, ControlNet을 섞으면 sampling이나 VAE decode 단계에서 tensor shape error가 날 수 있습니다. Claude가 stack trace와 graph를 연결할 수는 있지만, 목표 모델 계열의 공식 template이 더 좋은 호환성 기준입니다.
5. 작업 복사본에서 노드 하나만 변경하기
편집을 승인하기 전에 Claude에게 다음 계획을 요구하세요.
| 항목 | 반드시 답할 질문 |
|---|---|
| 기존 노드 | JSON의 정확한 type은 무엇인가 |
| 소유자 | Core, custom node, frontend extension 중 무엇인가 |
| 대체 노드 | 입력과 출력 type이 일치하는가 |
| Parameter migration | 유지할 widget values와 다시 설정할 값은 무엇인가 |
| Rollback | 이전 workflow-working.json을 어떻게 되돌릴 것인가 |
변경은 workflow-working.json에만, 한 번에 하나의 문제만 허용합니다. 편집할 때마다 다시 불러와 노드가 존재하는지, 연결이 유효한지, parameter가 밀리지 않았는지 확인합니다. “Update all custom nodes”는 두 번째 호환성 문제를 만들 수 있고 어떤 변경이 효과가 있었는지에 대한 근거도 없앱니다.
커뮤니티 페이지는 증상을 대조하는 데는 도움이 되지만 보편적 진단은 아닙니다. frontend issue #6328과 ComfyUI discussion #14344는 개별 사용자 보고입니다. 버전, 오류, 노드 맥락이 자신의 사례와 맞을 때만 참고하세요.
6. 현재형 최소 이미지 그래프 재구성하기
기존 graph에 오래된 LoRA, ControlNet, upscale, preview, utility branch가 많다면 모두 한꺼번에 고치는 것보다 중심을 다시 만드는 편이 안전합니다. ComfyUI의 공식 최소 Save 형식 예제를 기준으로 중심부를 재구성하세요. 이것은 직렬 체인이 아니라 분기 그래프입니다. 여러 출력이 KSampler로 모이고, VAEDecode에는 checkpoint의 VAE가 별도 경로로 들어갑니다.
| 출력 포트 | 입력 포트 |
|---|---|
CheckpointLoaderSimple.MODEL | KSampler.model |
CheckpointLoaderSimple.CLIP | positive 프롬프트용 CLIPTextEncode.clip |
CheckpointLoaderSimple.CLIP | negative 프롬프트용 CLIPTextEncode.clip |
positive 프롬프트의 CLIPTextEncode.CONDITIONING | KSampler.positive |
negative 프롬프트의 CLIPTextEncode.CONDITIONING | KSampler.negative |
EmptyLatentImage.LATENT | KSampler.latent_image |
KSampler.LATENT | VAEDecode.samples |
CheckpointLoaderSimple.VAE | VAEDecode.vae |
VAEDecode.IMAGE | SaveImage.images |
EmptyLatentImage는 conditioning을 입력받지 않습니다. KSampler에는 model, positive, negative, latent_image 네 입력이 각각 필요하고, VAEDecode에는 샘플링 결과인 samples와 checkpoint의 vae가 모두 필요합니다. 표와 같이 연결해야 최소 그래프를 실제로 큐에 넣고 이미지를 저장할 수 있습니다.
이 연결은 선택한 checkpoint의 아키텍처가 공식 예제와 일치할 때만 사용하세요. 새 모델은 다른 loader, text encoder, latent node 또는 VAE 경로를 요구할 수 있습니다. 그런 경우 이 그래프를 억지로 적용하지 말고 해당 모델의 공식 workflow를 따르세요. 기준 테스트에서는 Load Checkpoint에 이미 표시되는 호환 checkpoint를 선택하고 batch size는 1, 해상도는 적당히 낮게 설정하며 기존 optional branch는 아직 연결하지 않습니다. 기본 축이 통과하면 LoRA, ControlNet, upscaler, custom post-processing을 하나씩 추가하고 매번 다시 실행합니다.
새 graph를 기존과 똑같이 보이게 만드는 것이 목표가 아닙니다. 현재 확실히 작동하는 축을 먼저 증명한 뒤, 기존 워크플로에 정말 필요한 기능만 옮깁니다. Claude는 두 JSON을 비교해 migration map을 만들 수 있지만 실행 결과가 최종 acceptance test입니다.
7. 이미지 한 장을 실행하고 저장 결과 검증하기
열리기만 하는 워크플로는 복구된 것이 아닙니다. 공식 첫 이미지 생성 가이드에 따라 끝까지 확인하세요.
- 모델을 설치하거나 옮겼다면
R을 눌러 모델 목록을 갱신하고, 필요하면 재시작합니다. Load Checkpoint에 보이는 호환 모델을 선택했는지 확인합니다.Run을 클릭하거나Ctrl + Enter를 누릅니다.- Queue가 끝날 때까지 기다리고 missing node, validation error, 빨간 실패 노드가 없는지 봅니다.
- 이미지가
Save Image에 나타나는지 확인합니다. - 우클릭으로 로컬에 저장하고 파일명을 기록한 뒤 이미지 뷰어에서 다시 엽니다.
- 선택 사항으로 생성된 ComfyUI PNG를 화면에 다시 끌어 넣어 embedded workflow metadata가 읽히는지 확인합니다.
- 복구한 일반 형식 graph를
workflow-repaired.json으로 저장하고workflow-original.json은 그대로 둡니다.
Acceptance 기록에는 복구 워크플로 파일명, 출력 이미지 파일명, 사용 모델, 활성 custom nodes, 교체한 노드, 알려진 제한이 들어가야 합니다. 그래야 “복구 완료”가 근거 있는 상태가 됩니다.
한 경로가 계속 실패할 때
- Custom nodes를 꺼도 기본 워크플로가 실패: 기존 graph 편집을 멈추고 설치, 모델, 드라이버, frontend 기준선을 고칩니다.
- 기본은 되지만 기존 graph에 missing nodes가 남음: 소유자와 대체재 매핑을 계속하고 JSON type을 추측으로 바꾸지 않습니다.
- Graph는 로드되지만 생성이 실패:
Show report의 첫 실패 node부터 보고 메모리보다 먼저 model family와 연결을 확인합니다. - Extension 그룹을 켤 때 실패가 돌아옴: custom node 또는 frontend extension 하나가 남을 때까지 bisect합니다.
- 원래 노드가 유지보수되지 않음: 기능을 교체하거나 다시 만들고 동작 차이를 문서화합니다.
- Claude가 오류나 JSON 근거를 인용하지 않음: 제안을 가설로 취급하고 아직 실행하지 않습니다.
결론
이 작업에서 Claude는 검증되지 않은 자동 수리 버튼보다 근거 정리자와 변경 계획자로 쓸 때 가장 믿을 수 있습니다. 안정적인 순서는 백업 → 깨끗한 기준선 → 분류 → 최소 변경 → 이미지 한 장 → 저장 파일 확인입니다. 원본 graph를 보존하고 한 번에 하나의 변수만 바꾸며, 자신감 있는 설명이 아니라 실제 ComfyUI 출력으로 복구 여부를 판단하세요.
