docs/providers/comfy.md
OpenClaw ships a bundled comfy plugin for workflow-driven ComfyUI runs. The plugin is entirely workflow-driven, so OpenClaw does not try to map generic size, aspectRatio, resolution, durationSeconds, or TTS-style controls onto your graph.
| Property | Detail |
|---|---|
| Provider | comfy |
| Models | comfy/workflow |
| Shared surfaces | 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 and Comfy Cloud /api/* |
music_generate toolChoose between running ComfyUI on your own machine or using Comfy Cloud.
<Tabs> <Tab title="Local"> **Best for:** running your own ComfyUI instance on your machine or LAN.<Steps>
<Step title="Start ComfyUI locally">
Make sure your local ComfyUI instance is running (defaults to `http://127.0.0.1:8188`).
</Step>
<Step title="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.
</Step>
<Step title="Configure the provider">
Set `mode: "local"` and point at your workflow file. Here is a minimal image example:
```json5
{
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="Set the default model">
Point OpenClaw at the `comfy/workflow` model for the capability you configured:
```json5
{
agents: {
defaults: {
imageGenerationModel: {
primary: "comfy/workflow",
},
},
},
}
```
</Step>
<Step title="Verify">
```bash
openclaw models list --provider comfy
```
</Step>
</Steps>
<Steps>
<Step title="Get an API key">
Sign up at [comfy.org](https://comfy.org) and generate an API key from your account dashboard.
</Step>
<Step title="Set the API key">
Provide your key through one of these methods:
```bash
# Environment variable (preferred)
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"
```
</Step>
<Step title="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.
</Step>
<Step title="Configure the provider">
Set `mode: "cloud"` and point at your workflow file:
```json5
{
plugins: {
entries: {
comfy: {
config: {
mode: "cloud",
image: {
workflowPath: "./workflows/flux-api.json",
promptNodeId: "6",
outputNodeId: "9",
},
},
},
},
},
}
```
<Tip>
Cloud mode defaults `baseUrl` to `https://cloud.comfy.org`. You only need to set `baseUrl` if you use a custom cloud endpoint.
</Tip>
</Step>
<Step title="Set the default model">
```json5
{
agents: {
defaults: {
imageGenerationModel: {
primary: "comfy/workflow",
},
},
},
}
```
</Step>
<Step title="Verify">
```bash
openclaw models list --provider comfy
```
</Step>
</Steps>
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",
},
},
},
},
},
}
| Key | Type | Description |
|---|---|---|
mode | "local" or "cloud" | Connection mode. |
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. |
These keys apply inside the image, video, or music sections:
| Key | Required | Default | Description |
|---|---|---|---|
workflow or workflowPath | Yes | -- | 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 | -- | Polling interval in milliseconds for job completion. |
timeoutMs | No | -- | Timeout in milliseconds for the workflow run. |
The image and video sections also support:
| 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. |
```json5
{
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:
```json5
{
plugins: {
entries: {
comfy: {
config: {
image: {
workflowPath: "./workflows/edit-api.json",
promptNodeId: "6",
inputImageNodeId: "7",
inputImageInputName: "image",
outputNodeId: "9",
},
},
},
},
},
}
```
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "comfy/workflow",
},
},
},
}
```
Comfy video workflows support text-to-video and image-to-video through the configured graph.
<Note>
OpenClaw does not pass input videos into Comfy workflows. Only text prompts and single reference images are supported as inputs.
</Note>
```text
/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.
```json5
{
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.
<Tip>
If you only use image generation, the legacy flat config and the new nested `image` section are functionally equivalent.
</Tip>
```bash
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.