> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ComfyUI

OpenClaw는 워크플로 기반 ComfyUI 실행을 위한 번들 `comfy` Plugin을 제공합니다. 이 Plugin은 전적으로 워크플로 기반이므로, OpenClaw는 일반적인 `size`, `aspectRatio`, `resolution`, `durationSeconds`, 또는 TTS 스타일 제어를 그래프에 매핑하려고 하지 않습니다.

| 속성       | 세부 정보                                                                   |
| -------- | ----------------------------------------------------------------------- |
| Provider | `comfy`                                                                 |
| 모델       | `comfy/workflow`                                                        |
| 공유 표면    | `image_generate`, `video_generate`, `music_generate`                    |
| 인증       | 로컬 ComfyUI에는 없음, Comfy Cloud에는 `COMFY_API_KEY` 또는 `COMFY_CLOUD_API_KEY` |
| API      | ComfyUI `/prompt` / `/history` / `/view` 및 Comfy Cloud `/api/*`         |

## 지원 항목

* 워크플로 JSON을 통한 이미지 생성
* 업로드된 참조 이미지 1개를 사용한 이미지 편집
* 워크플로 JSON을 통한 비디오 생성
* 업로드된 참조 이미지 1개를 사용한 비디오 생성
* 공유 `music_generate` 도구를 통한 음악 또는 오디오 생성
* 구성된 노드 또는 일치하는 모든 출력 노드에서 결과 다운로드

## 시작하기

자신의 머신에서 ComfyUI를 실행할지, Comfy Cloud를 사용할지 선택하세요.

<Tabs>
  <Tab title="로컬">
    **가장 적합한 경우:** 자신의 머신 또는 LAN에서 ComfyUI 인스턴스를 직접 실행할 때.

    <Steps>
      <Step title="로컬에서 ComfyUI 시작">
        로컬 ComfyUI 인스턴스가 실행 중인지 확인하세요(기본값 `http://127.0.0.1:8188`).
      </Step>

      <Step title="워크플로 JSON 준비">
        ComfyUI 워크플로 JSON 파일을 내보내거나 만드세요. 프롬프트 입력 노드와 OpenClaw가 읽어야 할 출력 노드의 노드 ID를 기록해 두세요.
      </Step>

      <Step title="Provider 구성">
        `mode: "local"`을 설정하고 워크플로 파일을 가리키세요. 아래는 최소 이미지 예시입니다:

        ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
        {
          plugins: {
            entries: {
              comfy: {
                config: {
                  mode: "local",
                  baseUrl: "http://127.0.0.1:8188",
                  image: {
                    workflowPath: "./workflows/flux-api.json",
                    promptNodeId: "6",
                    outputNodeId: "9",
                  },
                },
              },
            },
          },
        }
        ```
      </Step>

      <Step title="기본 모델 설정">
        구성한 capability에 대해 OpenClaw가 `comfy/workflow` 모델을 가리키도록 설정하세요:

        ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
        {
          agents: {
            defaults: {
              imageGenerationModel: {
                primary: "comfy/workflow",
              },
            },
          },
        }
        ```
      </Step>

      <Step title="검증">
        ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
        openclaw models list --provider comfy
        ```
      </Step>
    </Steps>
  </Tab>

  <Tab title="Comfy Cloud">
    **가장 적합한 경우:** 로컬 GPU 리소스를 관리하지 않고 Comfy Cloud에서 워크플로를 실행할 때.

    <Steps>
      <Step title="API 키 받기">
        [comfy.org](https://comfy.org)에서 가입하고 계정 대시보드에서 API 키를 생성하세요.
      </Step>

      <Step title="API 키 설정">
        다음 방법 중 하나로 키를 제공하세요:

        ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
        # 환경 변수(권장)
        export COMFY_API_KEY="your-key"

        # 대체 환경 변수
        export COMFY_CLOUD_API_KEY="your-key"

        # 또는 config에 직접 입력
        openclaw config set plugins.entries.comfy.config.apiKey "your-key"
        ```
      </Step>

      <Step title="워크플로 JSON 준비">
        ComfyUI 워크플로 JSON 파일을 내보내거나 만드세요. 프롬프트 입력 노드와 출력 노드의 노드 ID를 기록해 두세요.
      </Step>

      <Step title="Provider 구성">
        `mode: "cloud"`를 설정하고 워크플로 파일을 가리키세요:

        ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
        {
          plugins: {
            entries: {
              comfy: {
                config: {
                  mode: "cloud",
                  image: {
                    workflowPath: "./workflows/flux-api.json",
                    promptNodeId: "6",
                    outputNodeId: "9",
                  },
                },
              },
            },
          },
        }
        ```

        <Tip>
          Cloud 모드에서 `baseUrl` 기본값은 `https://cloud.comfy.org`입니다. 사용자 지정 cloud 엔드포인트를 사용하는 경우에만 `baseUrl`을 설정하면 됩니다.
        </Tip>
      </Step>

      <Step title="기본 모델 설정">
        ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
        {
          agents: {
            defaults: {
              imageGenerationModel: {
                primary: "comfy/workflow",
              },
            },
          },
        }
        ```
      </Step>

      <Step title="검증">
        ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
        openclaw models list --provider comfy
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## 구성

Comfy는 공유 최상위 연결 설정과 capability별 워크플로 섹션(`image`, `video`, `music`)을 지원합니다:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  plugins: {
    entries: {
      comfy: {
        config: {
          mode: "local",
          baseUrl: "http://127.0.0.1:8188",
          image: {
            workflowPath: "./workflows/flux-api.json",
            promptNodeId: "6",
            outputNodeId: "9",
          },
          video: {
            workflowPath: "./workflows/video-api.json",
            promptNodeId: "12",
            outputNodeId: "21",
          },
          music: {
            workflowPath: "./workflows/music-api.json",
            promptNodeId: "3",
            outputNodeId: "18",
          },
        },
      },
    },
  },
}
```

### 공유 키

| 키                     | 타입                     | 설명                                                                    |
| --------------------- | ---------------------- | --------------------------------------------------------------------- |
| `mode`                | `"local"` 또는 `"cloud"` | 연결 모드입니다.                                                             |
| `baseUrl`             | string                 | 로컬은 기본값 `http://127.0.0.1:8188`, cloud는 `https://cloud.comfy.org`입니다. |
| `apiKey`              | string                 | 선택적 인라인 키이며, `COMFY_API_KEY` / `COMFY_CLOUD_API_KEY` env vars의 대안입니다. |
| `allowPrivateNetwork` | boolean                | cloud 모드에서 사설망/LAN `baseUrl`을 허용합니다.                                  |

### capability별 키

이 키들은 `image`, `video`, 또는 `music` 섹션 내부에 적용됩니다:

| 키                            | 필수 여부 | 기본값      | 설명                                             |
| ---------------------------- | ----- | -------- | ---------------------------------------------- |
| `workflow` 또는 `workflowPath` | 예     | --       | ComfyUI 워크플로 JSON 파일 경로입니다.                    |
| `promptNodeId`               | 예     | --       | 텍스트 프롬프트를 받는 노드 ID입니다.                         |
| `promptInputName`            | 아니요   | `"text"` | 프롬프트 노드의 입력 이름입니다.                             |
| `outputNodeId`               | 아니요   | --       | 출력 결과를 읽을 노드 ID입니다. 생략하면 일치하는 모든 출력 노드를 사용합니다. |
| `pollIntervalMs`             | 아니요   | --       | 작업 완료를 위한 폴링 간격(밀리초)입니다.                       |
| `timeoutMs`                  | 아니요   | --       | 워크플로 실행 제한 시간(밀리초)입니다.                         |

`image`와 `video` 섹션은 다음도 지원합니다:

| 키                     | 필수 여부             | 기본값       | 설명                        |
| --------------------- | ----------------- | --------- | ------------------------- |
| `inputImageNodeId`    | 예 (참조 이미지를 전달할 때) | --        | 업로드된 참조 이미지를 받는 노드 ID입니다. |
| `inputImageInputName` | 아니요               | `"image"` | 이미지 노드의 입력 이름입니다.         |

## 워크플로 세부 정보

<AccordionGroup>
  <Accordion title="이미지 워크플로">
    기본 이미지 모델을 `comfy/workflow`로 설정하세요:

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      agents: {
        defaults: {
          imageGenerationModel: {
            primary: "comfy/workflow",
          },
        },
      },
    }
    ```

    **참조 이미지 편집 예시:**

    업로드된 참조 이미지를 사용한 이미지 편집을 활성화하려면 이미지 config에 `inputImageNodeId`를 추가하세요:

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      plugins: {
        entries: {
          comfy: {
            config: {
              image: {
                workflowPath: "./workflows/edit-api.json",
                promptNodeId: "6",
                inputImageNodeId: "7",
                inputImageInputName: "image",
                outputNodeId: "9",
              },
            },
          },
        },
      },
    }
    ```
  </Accordion>

  <Accordion title="비디오 워크플로">
    기본 비디오 모델을 `comfy/workflow`로 설정하세요:

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      agents: {
        defaults: {
          videoGenerationModel: {
            primary: "comfy/workflow",
          },
        },
      },
    }
    ```

    Comfy 비디오 워크플로는 구성된 그래프를 통해 text-to-video와 image-to-video를 지원합니다.

    <Note>
      OpenClaw는 Comfy 워크플로에 입력 비디오를 전달하지 않습니다. 입력으로는 텍스트 프롬프트와 단일 참조 이미지만 지원됩니다.
    </Note>
  </Accordion>

  <Accordion title="음악 워크플로">
    번들 Plugin은 워크플로로 정의된 오디오 또는 음악 출력을 위한 음악 생성 provider를 등록하며, 이는 공유 `music_generate` 도구를 통해 노출됩니다:

    ```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
    /tool music_generate prompt="Warm ambient synth loop with soft tape texture"
    ```

    오디오 워크플로 JSON과 출력 노드를 가리키도록 `music` config 섹션을 사용하세요.
  </Accordion>

  <Accordion title="하위 호환성">
    중첩된 `image` 섹션 없이 기존 최상위 이미지 config도 계속 작동합니다:

    ```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
    {
      plugins: {
        entries: {
          comfy: {
            config: {
              workflowPath: "./workflows/flux-api.json",
              promptNodeId: "6",
              outputNodeId: "9",
            },
          },
        },
      },
    }
    ```

    OpenClaw는 이 레거시 형태를 이미지 워크플로 config로 취급합니다. 즉시 마이그레이션할 필요는 없지만, 새 설정에는 중첩된 `image` / `video` / `music` 섹션을 권장합니다.

    <Tip>
      이미지 생성만 사용하는 경우, 레거시 평면 config와 새 중첩 `image` 섹션은 기능적으로 동일합니다.
    </Tip>
  </Accordion>

  <Accordion title="Live 테스트">
    번들 Plugin에 대한 opt-in live coverage가 있습니다:

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
    ```

    matching Comfy 워크플로 섹션이 구성되지 않은 경우, live 테스트는 개별 이미지, 비디오, 또는 음악 케이스를 건너뜁니다.
  </Accordion>
</AccordionGroup>

## 관련 항목

<CardGroup cols={2}>
  <Card title="이미지 생성" href="/ko/tools/image-generation" icon="image">
    이미지 생성 도구 구성 및 사용법입니다.
  </Card>

  <Card title="비디오 생성" href="/ko/tools/video-generation" icon="video">
    비디오 생성 도구 구성 및 사용법입니다.
  </Card>

  <Card title="음악 생성" href="/ko/tools/music-generation" icon="music">
    음악 및 오디오 생성 도구 설정입니다.
  </Card>

  <Card title="Provider 디렉터리" href="/ko/providers/index" icon="layers">
    모든 provider 및 모델 참조 개요입니다.
  </Card>

  <Card title="구성 참조" href="/ko/gateway/config-agents#agent-defaults" icon="gear">
    에이전트 기본값을 포함한 전체 구성 참조입니다.
  </Card>
</CardGroup>