ComfyUI

OpenClaw ships a bundled comfy plugin for workflow-driven ComfyUI runs. The plugin is entirely workflow-driven: OpenClaw does not map generic size, aspectRatio, resolution, durationSeconds, or TTS-style controls onto your graph.

Property	Detail
Provider	comfy
Model	comfy/workflow
Shared tools	image_generate, video_generate, music_generate
Auth	None for local ComfyUI; COMFY_API_KEY or COMFY_CLOUD_API_KEY for Comfy Cloud
API	ComfyUI /prompt / /history / /view; Comfy Cloud /api/*

What it supports

• Image generation and editing from a workflow JSON (edit takes 1 uploaded reference image)
• Video generation from a workflow JSON, text-to-video or image-to-video (1 reference image)
• Music/audio generation through the shared music_generate tool, with an optional 1 reference image
• Output download from a configured node, or from all matching output nodes when none is configured

Getting started

Choose between running ComfyUI on your own machine or using Comfy Cloud.

Local

Best for: running your own ComfyUI instance on your machine or LAN.

1. Start ComfyUI locally

   Make sure your local ComfyUI instance is running (defaults to http://127.0.0.1:8188).

2. Prepare your workflow JSON

   Export or create a ComfyUI workflow JSON file. Note the node IDs for the prompt input node and the output node you want OpenClaw to read from.

3. Configure the provider

   Set mode: "local" and point at your workflow file. Minimal image example:

   {
     plugins: {
       entries: {
         comfy: {
           config: {
             mode: "local",
             baseUrl: "http://127.0.0.1:8188",
             image: {
               workflowPath: "./workflows/flux-api.json",
               promptNodeId: "6",
               outputNodeId: "9",
             },
           },
         },
       },
     },
   }
   
4. Set the default model

   Point OpenClaw at the comfy/workflow model for the capability you configured:

   {
     agents: {
       defaults: {
         imageGenerationModel: {
           primary: "comfy/workflow",
         },
       },
     },
   }
   
5. Verify

   openclaw models list --provider comfy
   

Comfy Cloud

Best for: running workflows on Comfy Cloud without managing local GPU resources.

1. Get an API key

   Sign up at comfy.org and generate an API key from your account dashboard.

2. Set the API key

   Provide your key through any of these methods:

   # Onboarding flag
   openclaw onboard --comfy-api-key "your-key"
   
   # Environment variable (preferred for daemons)
   export COMFY_API_KEY="your-key"
   
   # Alternative environment variable
   export COMFY_CLOUD_API_KEY="your-key"
   
   # Or inline in config
   openclaw config set plugins.entries.comfy.config.apiKey "your-key"
   
3. Prepare your workflow JSON

   Export or create a ComfyUI workflow JSON file. Note the node IDs for the prompt input node and the output node.

4. Configure the provider

   Set mode: "cloud" and point at your workflow file:

   {
     plugins: {
       entries: {
         comfy: {
           config: {
             mode: "cloud",
             image: {
               workflowPath: "./workflows/flux-api.json",
               promptNodeId: "6",
               outputNodeId: "9",
             },
           },
         },
       },
     },
   }
   

   Cloud mode defaults baseUrl to https://cloud.comfy.org. Set baseUrl only for a custom cloud endpoint.

5. Set the default model

   {
     agents: {
       defaults: {
         imageGenerationModel: {
           primary: "comfy/workflow",
         },
       },
     },
   }
   
6. Verify

   openclaw models list --provider comfy
   

Configuration

Comfy supports shared top-level connection settings plus per-capability workflow sections (image, video, music):

{
  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",
          },
        },
      },
    },
  },
}

Shared keys

Key	Type	Description
mode	"local" or "cloud"	Connection mode. Defaults to "local".
baseUrl	string	Defaults to http://127.0.0.1:8188 for local or https://cloud.comfy.org for cloud.
apiKey	string	Optional inline key, alternative to COMFY_API_KEY / COMFY_CLOUD_API_KEY env vars.
allowPrivateNetwork	boolean	Allow a private/LAN baseUrl in cloud mode or a local private-DNS FQDN.

In local mode, loopback/private IP literals and single-label service names such as http://comfyui:8188 work without allowPrivateNetwork. Public-looking private-DNS FQDNs such as https://comfy.local.example.com require allowPrivateNetwork: true. Private-origin trust stays scoped to the configured scheme, hostname, and port; local redirects cannot leave the configured hostname, while cloud redirects to public CDNs are checked with the default SSRF policy.

Per-capability keys

These keys apply inside the image, video, or music sections:

Key	Required	Default	Description
workflow or workflowPath	Yes	—	Inline workflow JSON, or path to the ComfyUI workflow JSON file.
promptNodeId	Yes	—	Node ID that receives the text prompt.
promptInputName	No	"text"	Input name on the prompt node.
outputNodeId	No	—	Node ID to read output from. If omitted, all matching output nodes are used.
pollIntervalMs	No	1500	Polling interval in milliseconds for job completion.
timeoutMs	No	300000	Timeout in milliseconds for the workflow run.

The image and video sections also support a reference-image input node:

Key	Required	Default	Description
inputImageNodeId	Yes (when passing a reference image)	—	Node ID that receives the uploaded reference image.
inputImageInputName	No	"image"	Input name on the image node.

apiKey accepts either a literal string or a secret reference object.

Workflow details

Image workflows

Set the default image model to comfy/workflow:

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "comfy/workflow",
      },
    },
  },
}

Reference-image editing example:

To enable image editing with an uploaded reference image, add inputImageNodeId to your image config:

{
  plugins: {
    entries: {
      comfy: {
        config: {
          image: {
            workflowPath: "./workflows/edit-api.json",
            promptNodeId: "6",
            inputImageNodeId: "7",
            inputImageInputName: "image",
            outputNodeId: "9",
          },
        },
      },
    },
  },
}

Video workflows

Set the default video model to comfy/workflow:

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "comfy/workflow",
      },
    },
  },
}

Comfy video workflows support text-to-video and image-to-video through the configured graph.

OpenClaw does not pass input videos into Comfy workflows. Only text prompts and single reference images are supported as inputs.

Music workflows

The bundled plugin registers a music-generation provider for workflow-defined audio or music outputs, surfaced through the shared music_generate tool. It accepts an optional reference image (up to 1):

/tool music_generate prompt="Warm ambient synth loop with soft tape texture"

Use the music config section to point at your audio workflow JSON and output node.

Backward compatibility

Existing top-level image config (without the nested image section) still works:

{
  plugins: {
    entries: {
      comfy: {
        config: {
          workflowPath: "./workflows/flux-api.json",
          promptNodeId: "6",
          outputNodeId: "9",
        },
      },
    },
  },
}

OpenClaw treats that legacy shape as the image workflow config. You do not need to migrate immediately, but the nested image / video / music sections are recommended for new setups. If you only use image generation, the legacy flat config and the new nested image section are functionally equivalent.

Live tests

Opt-in live coverage exists for the bundled plugin:

OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts

The live test skips individual image, video, or music cases unless the matching Comfy workflow section is configured.

Related

Image Generation

Image generation tool configuration and usage.

Video Generation

Video generation tool configuration and usage.

Music Generation

Music and audio generation tool setup.

Provider Directory

Overview of all providers and model refs.

Configuration reference

Full config reference including agent defaults.