CLAUDE CODE · COMFYUI JSON

ComfyUI 워크플로 JSON 읽기 — 클로드 코드로 노드 연결 풀고 값 고치기

junetapa 2026. 11. 21 업데이트 약 16분

이 글을 따라 하면 ComfyUI 워크플로 JSON(노드 설정과 연결을 글자로 담은 파일)을 클로드 코드에 읽혀 ‘어느 노드의 어느 출력이 어디로 들어가는지’ 표로 받고, 지정한 값 하나만 고친 사본을 다시 불러와 확인할 수 있다. 준비물은 실행되는 ComfyUI, 설치된 클로드 코드, 본인이 만든 워크플로 파일 하나다. 사본 만들기·읽기·수정·재확인 네 단계에 약 20분을 잡는다. 단계 수로 잡은 어림이며 이미지 생성 시간은 뺐다.

2026년 11월 21일 공식 문서와 소스 코드를 직접 열어 대조하고, 공식 문서 범위로 정리했다. 이 글에서 ComfyUI를 실행하거나 클로드의 수정 성공을 실측하지는 않았다. 아래 요청문과 확인표는 독자가 자신의 파일로 따라 쓰는 틀이다.

클로드 제대로 쓰기

이 글은 «클로드 제대로 쓰기» 시리즈의 28번째 글이다. 첫 글 클로드 처음 쓰기와 앞 편 클로드 코드로 ComfyUI 설치 오류 고치기를 잇는다. 이번에는 실행 환경을 고치는 대신 워크플로 파일의 연결과 설정을 읽는다.

ComfyUI 워크플로 JSON, 저장 형식부터 가른다

같은 JSON 확장자라도 담긴 내용은 다르다. 일반 저장 형식은 편집 화면을 다시 열기 위한 자료이고, API 형식은 실행에 필요한 노드와 입력을 전달하는 자료다. API는 프로그램끼리 요청을 주고받는 통로라는 뜻이다. 공식 안내는 API 형식에서 위치·색·그룹·노드 크기 같은 화면 정보를 생략한다고 설명한다.

‘노드’는 입력을 받아 처리하고 결과를 내보내는 상자다. ‘워크플로’는 그 상자들을 연결한 작업 흐름이다. 클로드에게 파일을 읽힐 때는 이미지에 보이는 상자 이름만 설명하기보다, 실제 노드 식별자와 연결 정보를 근거로 요구해야 한다. 같은 종류의 노드가 반복되면 이름만으로는 어느 상자를 가리키는지 알기 어렵다.

파일에서 보이는 모양읽을 때 주로 볼 항목보존해야 할 것
최상위에 nodes와 linksnodes 안의 id·type, 연결선, widgets_values화면 위치·그룹과 노드별 설정
노드 ID 아래에 class_type과 inputs노드 종류, 입력 이름, 연결된 출력실행할 입력과 노드 식별자
두 모습이 섞이거나 더 큰 자료 안에 들어 있음실제 워크플로가 들어 있는 위치바깥 자료를 함부로 버리지 않기

이 표의 앞 행은 화면용 스키마와 프런트엔드 소스에, 다음 행은 공식 API 예제에 근거한 읽기 기준이다. 노드 ID는 파일 안에서 상자를 식별하는 값이다. 화면에서 붙인 별명과 ID를 같은 것으로 취급하면 설명이 엉뚱한 노드로 이어질 수 있다.

일반 저장본은 화면 배치를 되살리는 데 쓰이므로 처음에는 그것을 기준으로 둔다. 생성한 PNG에서 작업을 되찾아야 한다면 ComfyUI 워크플로 불러오기에서 메타데이터가 남아 있는지부터 살필 수 있다. 여기서는 불러오기 자체보다, 확보한 JSON을 읽고 수정할 범위를 정하는 데 집중한다.

왼쪽 노드 그래프와 같은 구조를 색 맞춘 블록으로 겹쳐 보인 오른쪽 그림 — 화면의 연결과 JSON 안의 구조가 같은 내용이라는 개념
화면의 상자와 선은 JSON 안에서 노드 ID와 연결 정보로 적힌다.

원본은 보관하고 읽을 사본을 만든다

ComfyUI 화면에서 본인이 만든 작업을 저장하고, 별도 폴더에 복사한다. 아래는 이미 만들어 둔 예시 작업 폴더에서 실행하는 PowerShell 명령이다. PowerShell은 Windows 터미널에서 명령을 실행하는 셸이다. 폴더 위치와 파일 이름은 자신의 것으로 바꾼다. 같은 사본 이름이 있으면 덮어쓰지 않고 멈추도록 했다.

powershell
Set-Location -LiteralPath 'D:\AI\workflow-review'
if (Test-Path -LiteralPath '.\workflow.original.json') {
    throw '보관 사본이 이미 있다. 다른 이름을 정한다.'
}
Copy-Item -LiteralPath '.\workflow.json' -Destination '.\workflow.original.json'
Get-Content -LiteralPath '.\workflow.json' -Raw | ConvertFrom-Json | Out-Null
  1. 폴더에 원본과 보관 사본이 따로 있는지 본다. 잘 됐으면 내용이 같은 파일을 각각 찾을 수 있다. 파일을 못 찾는다는 오류가 나면 현재 폴더와 저장 위치를 먼저 맞춘다.
  2. JSON 읽기가 오류 없이 끝나는지 본다. 잘 됐으면 마지막 명령은 별도 문구 없이 끝난다. 따옴표나 쉼표 오류가 나오면 그 메시지를 남기고, 형식이 깨진 채 수정 요청을 이어가지 않는다.
  3. 읽힐 파일에서 민감한 경로와 프롬프트 내용을 살핀다. 필요한 부분만 남긴 사본으로 작업한다. 가린 경로가 실제 실행 경로인 것처럼 수정되면 파일을 못 찾을 수 있으므로, 설명용 사본인지 실행용 사본인지도 적는다.

이 명령은 JSON 문법만 읽는다. 모델이 설치돼 있는지, 연결 자료형이 맞는지, 생성 결과가 나오는지는 알 수 없다. 괄호가 맞는 문서와 실행되는 작업은 서로 다른 확인 단계다.

최소한 이것만

화면용 저장본을 보관하고, 클로드가 읽을 파일 이름을 정확히 지정한다. 노드를 알아보지 못했다면 값부터 바꾸지 않는다. 먼저 어느 형식인지와 무엇을 근거로 그렇게 판단했는지 답을 받는다.

일반 저장본·API 내보내기·보관 사본을 나눈 도해 — 형식 판별 후 원본과 수정 대상을 분리한다
화면용 저장본을 기준으로 두고 수정할 파일을 별도로 정한다.

ComfyUI 워크플로 수정, 노드와 설정 이름을 묶는다

처음 수정은 연결을 다시 짜기보다 이미 식별한 노드의 설정값을 바꾸는 작업으로 좁히는 편이 낫다. 예를 들어 기본 KSampler의 steps는 반복해서 노이즈를 줄이는 단계 수다. 확인한 소스의 기본값은 20이며, 허용 범위는 1부터 10000이다. 이 범위는 입력 검증 조건이지, 그 안의 어떤 값이든 좋은 그림을 만든다는 추천표가 아니다.

같은 소스에서 cfg 기본값은 8.0, denoise 기본값은 1.0이다. 기본값을 안다고 해서 읽은 워크플로의 값까지 그와 같지는 않다. ‘기본으로 돌려 줘’라는 말은 바꿀 항목을 여러 개로 넓힐 수 있다. 아래에서는 학습용 변경 목표를 steps의 기본값으로 명시하고 다른 설정은 유지한다.

설정값이 놓인 위치도 형식에 따라 다르다. API 예제는 inputs 안에 steps처럼 이름이 붙은 값을 넣지만, 화면용 스키마의 widgets_values는 배열 또는 객체를 허용한다. 위젯은 노드 안에서 값을 고르는 입력 칸이다. 화면용 배열에서 ‘앞에서 몇 번째가 steps’라고 외워 다른 파일에 그대로 적용하면 안 되는 이유다.

특히 화면에서 값을 직접 입력하던 항목을 연결 입력으로 바꿨거나 추가 기능이 노드 구성을 바꾼 경우에는, 저장된 값의 대응 관계를 더 읽어야 한다. 필드에 숫자가 있다는 이유만으로 의미를 정하지 않는다. 기본 노드의 소스와 화면의 항목 이름이 맞는지까지 물어야 한다.

그래프의 한 노드에서 다이얼을 돌리고 옆에 흐린 복제본을 백업으로 둔 장면 — 사본을 남기고 지정한 설정 하나만 고치는 개념
바꿀 노드와 설정을 함께 지정하고, 원본은 따로 남긴다.

변경안을 받은 뒤 사본에만 적용한다

text
앞에서 식별한 기본 KSampler 중 사용자가 지정한 노드를 대상으로 해 줘.
대상 노드 ID: 여기에 실제 ID를 적음
변경할 항목: steps
목표값: 20
현재값은 workflow.json에서 읽고, 추측해서 채우지 마.

먼저 변경 전 값과 수정할 JSON 위치를 보여 줘.
화면용 형식이면 widgets_values와 steps가 대응한다는 근거도 적어 줘.
근거가 없으면 위치를 짐작해서 바꾸지 말고 멈춰 줘.

사용자가 변경안을 확인한 뒤 workflow.edited.json이라는 새 파일로 저장해 줘.
같은 이름이 있으면 덮어쓰지 마.
원본과 보관 사본은 유지하고, 지정한 steps 외의 설정과 연결은 유지해 줘.
파일 전체 재정렬이나 형식 버전 변경도 하지 마.
저장 뒤에는 JSON을 읽을 수 있는지와 실제로 달라진 값만 보고해 줘.

목표값은 확인한 기본 KSampler 소스에서 가져온 예시다. 현재값이 이미 같다면 바뀔 내용이 없다는 답이 맞다. 기본 KSampler가 아닌 다른 샘플러를 골랐다면 이름을 비슷하게 고쳐 쓰지 말고, 해당 노드의 설정 정의부터 다시 읽는다.

  1. 변경 전 위치와 값을 읽는다. 잘 됐으면 답에 지정한 ID와 steps가 함께 나온다. 다른 KSampler가 선택됐으면 그 자리에서 대상을 바로잡는다.
  2. 변경안을 읽고 승인한다. 공식 문서 기준으로 계획을 승인하면 Plan mode를 벗어나 고른 권한 모드로 넘어간다. 처음이라면 승인 선택지 중 «Yes, manually approve edits»를 고르면 편집 한 건마다 다시 확인할 수 있다. 잘 됐으면 새 파일의 이름과 적용 범위가 앞서 정한 내용과 같다.
  3. 변경된 필드 목록을 받는다. 잘 됐으면 steps만 달라지고 모델·시드·연결·화면 배치는 그대로다. 여러 항목이 함께 바뀌면 이유를 읽기 전에는 ComfyUI에서 실행하지 않는다.

클로드의 보고만 믿지 말고 바뀐 값을 직접 꺼내 본다. 아래는 API 형식 파일에서 3번 노드의 steps를 원본과 수정본에서 하나씩 읽는 PowerShell 명령이다. 노드 ID 3은 공식 예제의 KSampler 번호이므로 자신의 파일 번호로 바꾼다.

powershell
(Get-Content -LiteralPath '.\workflow.original.json' -Raw | ConvertFrom-Json).'3'.inputs.steps
(Get-Content -LiteralPath '.\workflow.edited.json' -Raw | ConvertFrom-Json).'3'.inputs.steps

화면용 저장본이라면 nodes 목록에서 같은 ID의 widgets_values를 꺼내 비교한다.

powershell
(Get-Content -LiteralPath '.\workflow.edited.json' -Raw | ConvertFrom-Json).nodes | Where-Object id -eq 3 | Select-Object id, type, widgets_values

잘 됐으면 두 줄의 숫자가 다르고, 수정본 쪽이 목표값이다. 아무것도 나오지 않으면 노드 ID가 틀렸거나 형식을 잘못 짚은 것이다. diff(바뀐 부분을 전후로 비교한 결과)를 받을 때도 들여쓰기만 달라진 줄과 실제 값이 달라진 줄을 나눠 달라고 한다. 파일이 통째로 다시 정렬됐다면 노드 ID와 필드 경로 기준으로 바뀐 값만 다시 요구한다.

더 해 보기

구형 화면용 v0.4의 연결선은 연결 ID·출발 노드·출력 칸·도착 노드·입력 칸·자료형의 순서로 적힌 배열이다. 화면용 v1.0은 origin_id·origin_slot·target_id·target_slot 같은 이름 붙은 필드를 쓴다. 버전 숫자만 고치는 방식으로 서로 변환하지 않는다. 실제 연결 자료의 모양까지 달라지기 때문이다.

연결을 바꾸려면 값을 바꾸는 요청보다 많은 근거가 필요하다. 화면용 노드에는 전체 연결 목록과 별개로 입출력의 연결 참조가 들어간다. 전체 links의 도착 노드만 바꾸고 노드 쪽 참조를 남겨 두면 서로 어긋날 수 있다는 뜻이다. 처음에는 클로드에게 연결 변경 후보와 맞춰야 할 항목만 설명받고, 화면에서 연결을 다시 저장하는 경로가 검토하기 쉽다.

권한 모드를 더 알고 싶으면 클로드 코드 권한 모드를 함께 볼 수 있다. 파일 수정 허용 여부는 클로드가 할 수 있는 동작을 정하고, 변경 요청의 노드·필드 지정은 이번에 할 일을 정한다. 읽기에서 편집으로 넘어갈 때 두 범위를 다시 맞춘다.

대상 노드 식별·필드 대응 근거·변경안·새 파일·값 비교로 이어지는 도해 — 근거가 없으면 수정 전에 멈춘다
기본값을 적용하더라도 어느 노드의 어느 필드인지 먼저 정한다.

ComfyUI 워크플로를 다시 불러와 확인하는 순서

수정 파일이 생기면 먼저 문법을 읽고, 그다음 ComfyUI 화면에서 불러온다. JSON을 읽을 수 있다는 결과는 파일의 괄호와 값 표현을 해석했다는 뜻이다. 실행 환경에 없는 노드나 모델까지 생겼다는 뜻은 아니다. 공식 노드 안내도 누락된 노드를 별도의 상태로 설명한다.

수정 사본의 문법을 읽는 명령은 다음과 같다. 파일이 없다는 오류가 나면 클로드가 답에 적은 저장 위치와 실제 위치를 맞춘다. 저장했다고 설명했더라도 파일이 없으면 적용된 것으로 기록하지 않는다.

powershell
Get-Content -LiteralPath '.\workflow.edited.json' -Raw | ConvertFrom-Json | Out-Null

화면용 파일이면 기존 작업을 먼저 저장하고 새 탭이나 별도 작업 화면에서 수정본을 불러온다. API 형식도 화면으로 읽을 수 있지만 원래 배치는 보존되지 않는다는 것이 공식 안내다. 상자 위치가 달라졌다고 곧바로 연결이 틀렸다고 판정하거나, 반대로 화면이 열렸다는 이유만으로 생성까지 성공했다고 판정하지 않는다.

파일 카드가 빛나는 화살표를 따라 노드 캔버스로 다시 불려 들어가는 장면 — 수정 사본을 ComfyUI에 다시 불러와 확인하는 개념
파일 읽기 성공 다음에는 화면의 값과 실제 생성 결과를 확인한다.

값·연결·실행 결과를 따로 적는다

  1. 수정본을 불러오고 지정한 KSampler를 찾는다. 잘 됐으면 대상 ID의 steps에 요청한 값이 보인다. 값이 다르면 이전 탭이나 원본을 열었는지부터 살핀다.
  2. 모델과 프롬프트 입력, 결과 저장 쪽의 연결을 본다. 잘 됐으면 설명받은 경로가 화면에서도 이어진다. 노드가 누락됐거나 입력이 비어 있으면 문법 검사를 되풀이하는 대신 그 노드와 입력 이름을 클로드에게 읽힌다.
  3. 원본과 같은 모델·입력 이미지·프롬프트 조건에서 실행한다. 잘 됐으면 대기열 접수 뒤 처리가 끝나고 해당 저장 노드의 결과를 찾을 수 있다. 실패하면 오류 메시지와 노드 ID를 남긴다.
  4. 결과 파일과 바뀐 설정을 함께 기록한다. 잘 됐으면 어느 파일로 실행했고 무엇이 달랐는지 다시 설명할 수 있다. 결과가 마음에 들지 않는 경우도 실행 실패와 나눠 적어야 다음 수정의 목표가 분명해진다.

기본 KSampler의 seed에는 생성 뒤 값을 바꾸는 제어가 정의돼 있다. seed는 시작 노이즈를 정하는 값이다. 원본과 수정본을 비교할 때 실행할 때마다 이 값까지 달라지면 steps 변경만의 영향이라고 보기 어렵다. 비교 전에 같은 시드가 실제 입력되는지 보고, 다른 모델이나 환경에서도 그림이 같아진다고 확대하지 않는다.

실행 버튼 뒤의 오류는 단서가 더 구체적이다. 서버 소스에는 필수 입력 누락의 required_input_missing, 연결 자료형 불일치의 return_type_mismatch, 허용 목록 밖 값의 value_not_in_list가 따로 있다. 클로드에게 ‘실패했다’만 보내기보다 오류 이름과 대상 입력을 함께 주면, 설치 문제와 연결 문제를 나눠 읽기 쉽다.

확인한 단계성공했을 때 남는 것실패하면 다시 볼 곳
문법 읽기JSON 해석 오류가 없음따옴표·쉼표·파일 위치
화면 불러오기대상 노드와 바뀐 값이 보임형식·노드 누락·다른 탭
실행 전 검증입력 검증을 통과해 접수됨필수 입력·연결 자료형·허용 값
생성 완료해당 저장 노드의 결과가 있음모델 로딩·실행 오류·저장 위치

표의 실행 전 검증과 생성 완료는 따로 봐야 한다. 공식 서버 문서는 /prompt가 입력을 검증한 뒤 대기열에 넣고, 실패하면 error와 node_errors를 돌려준다고 설명한다. 대기열에 들어갔다는 기록만으로 생성 결과를 대신할 수 없다.

API JSON을 실제 요청으로 보내는 방법은 ComfyUI API 파이썬 사용법에서 이어 볼 수 있다. 화면에서 고친 작업을 API용으로 옮기려면 일반 저장본을 다시 불러온 뒤 File → Export Workflow (API)로 내보내는 공식 절차를 따른다. API 파일을 따로 고쳤다면 화면용 저장본에도 같은 변경이 반영됐다고 가정하지 않는다.

수정이 잘못됐을 때는 보관 사본을 새로 불러와 변경 전 상태와 비교한다. 이번 작업에서 패키지나 모델까지 바꾸지 않았다면 되돌릴 파일 범위도 좁다. 오류를 고치는 동안 다른 설치 작업이 들어갔다면 JSON 사본만으로 그 환경까지 되돌아간다고 적어서는 안 된다.

문법 읽기·화면 값·입력 검증·생성 완료를 구별한 도해 — 각 단계의 성공 증거를 따로 남긴다
화면이 열림과 생성 완료를 다른 결과로 기록한다.

자주 묻는 것

일반 JSON과 API JSON 중 무엇을 읽혀야 하나요?

화면을 유지하며 고치려면 일반 저장본을 기준으로 읽힌다. 실행할 입력 이름을 추적하려면 API 내보내기를 함께 참고할 수 있다. API 형식에서는 화면 배치가 빠지므로, API 파일만 남겨 두고 원래 편집 배치가 유지될 것으로 기대하지 않는다. 파일 이름에 형식과 역할을 적으면 다시 불러올 때 혼동을 줄일 수 있다.

클로드가 widgets_values의 위치를 단정하면 그대로 바꿔도 되나요?

노드 ID와 항목 이름이 어떻게 대응하는지 근거를 먼저 받는다. 구형 공식 스키마도 이 필드에 배열과 객체를 허용한다. 다른 워크플로에서 본 순서를 그대로 적용하는 설명은 내 파일의 증거가 아니다. 대응 관계를 읽을 수 없다면 화면에서 해당 값을 바꾸고 다시 저장하는 편이 분명하다.

노드 번호가 크면 나중에 실행되나요?

ID는 연결의 대상을 찾는 식별자다. 처리 흐름은 입력이 어떤 출력에 의존하는지 따라 읽어야 한다. API 예제의 VAEDecode도 입력 안에서 다른 노드의 출력을 참조한다. 파일에서 숫자가 큰 순서로 설명받기보다 결과 노드까지 이어지는 경로를 요구한다.

JSON 검사가 통과했는데 왜 ComfyUI에서 실패하나요?

문법 검사에는 실행에 필요한 노드 정의나 모델 목록이 없다. 서버 소스는 필수 입력, 연결 자료형, 선택 가능한 값 등을 별도로 검증한다. 오류 메시지의 입력 이름과 대상 노드를 읽혀야 다음에 볼 곳이 정해진다. 문법 성공을 근거로 재설치를 제안받았다면 그 사이의 원인 근거가 빠진 것이다.

기본 KSampler의 기본값이면 어느 모델에나 맞나요?

소스의 기본값은 프로그램이 입력 칸에 두는 출발값이다. 원하는 결과를 보장하는 모델별 권장 설정과는 용도가 다르다. 자신의 워크플로가 이미 정한 값이 있다면 바꿀 이유부터 적고, 지정한 설정 외의 조건을 유지한 채 결과를 비교한다.

정리 — 연결의 근거를 읽고 사본으로 되돌아온다

클로드 코드에 ComfyUI 워크플로를 읽힐 때 먼저 받을 답은 형식 판별과 노드 ID가 붙은 연결 설명이다. 그다음에는 바꿀 노드와 설정을 묶어 지정하고, 현재값과 저장 위치를 파일에서 읽게 한다. 수정은 별도 파일에 남겨야 결과가 잘못됐을 때 원본과 다시 비교할 수 있다.

마지막 확인은 문법 읽기에서 끝나지 않는다. ComfyUI에서 수정본의 값을 보고, 연결을 살피고, 실제 결과가 나오는 데까지 따라간다. 설명이 설득력 있는지보다 파일의 근거와 화면의 값, 실행 결과가 같은 변경을 가리키는지가 판단 기준이다. 따라 하다 막힌 분은 오류 이름과 노드 ID부터 적어 두면 다음 질문이 훨씬 짧아진다.

노드 그래프와 구조화된 문서가 나란히 있고 작은 로봇이 곁에 있는 대표 장면 — 클로드 코드로 ComfyUI 워크플로 JSON을 읽고 고치는 흐름
ComfyUI 워크플로 JSON 읽기 — 클로드 코드로 노드 연결 풀고 값 고치기

참고 자료

  1. Comfy-Org. Workflow API Format — 공식 문서·소스 원문 대조(2026-11-21 확인). docs.comfy.org
  2. Comfy-Org. Workflow JSON — 공식 문서·소스 원문 대조(2026-11-21 확인). docs.comfy.org
  3. Comfy-Org. Workflow JSON 0.4 — 공식 문서·소스 원문 대조(2026-11-21 확인). docs.comfy.org
  4. Anthropic. Choose a permission mode — 공식 문서·소스 원문 대조(2026-11-21 확인). code.claude.com
  5. Anthropic. CLI reference — 공식 문서·소스 원문 대조(2026-11-21 확인). code.claude.com
  6. Comfy-Org. Nodes — 공식 문서·소스 원문 대조(2026-11-21 확인). docs.comfy.org
  7. Comfy-Org. Server Routes — 공식 문서·소스 원문 대조(2026-11-21 확인). docs.comfy.org
  8. Comfy-Org/ComfyUI. nodes.py — 공식 문서·소스 원문 대조(2026-11-21 확인). github.com
  9. Comfy-Org/ComfyUI. execution.py — 공식 문서·소스 원문 대조(2026-11-21 확인). github.com
  10. Comfy-Org/ComfyUI_frontend. LLink.ts — 공식 문서·소스 원문 대조(2026-11-21 확인). github.com
  11. Comfy-Org/ComfyUI_frontend. workflowSchema.ts — 공식 문서·소스 원문 대조(2026-11-21 확인). github.com
ComfyUI워크플로JSON클로드코드노드연결API형식KSampler설정수정워크플로검증클로드
junetapa(박준철)
AI 도구를 직접 굴려 보고 남은 기록을 정리한다.
Twitter Facebook URL 복사