Providers
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_generatetool, 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.
Start ComfyUI locally
Make sure your local ComfyUI instance is running (defaults to http://127.0.0.1:8188).
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.
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", }, }, }, }, },}Set the default model
Point OpenClaw at the comfy/workflow model for the capability you configured:
{ agents: { defaults: { imageGenerationModel: { primary: "comfy/workflow", }, }, },}Verify
openclaw models list --provider comfyComfy Cloud
Best for: running workflows on Comfy Cloud without managing local GPU resources.
Get an API key
Sign up at comfy.org and generate an API key from your account dashboard.
Set the API key
Provide your key through any of these methods:
# Onboarding flagopenclaw onboard --comfy-api-key "your-key" # Environment variable (preferred for daemons)export COMFY_API_KEY="your-key" # Alternative environment variableexport COMFY_CLOUD_API_KEY="your-key" # Or inline in configopenclaw config set plugins.entries.comfy.config.apiKey "your-key"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.
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", }, }, }, }, },}Set the default model
{ agents: { defaults: { imageGenerationModel: { primary: "comfy/workflow", }, }, },}Verify
openclaw models list --provider comfyConfiguration
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. |
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.
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.tsThe live test skips individual image, video, or music cases unless the matching Comfy workflow section is configured.
Related
Image generation tool configuration and usage.
Video generation tool configuration and usage.
Music and audio generation tool setup.
Overview of all providers and model refs.
Full config reference including agent defaults.
