ComfyUI in OpenClaw: MCP OAuth and Workflow Plugin Setup

For account OAuth plus Comfy's built-in discovery and generation tools, use Comfy Cloud's hosted MCP server. For workflow-driven runs through OpenClaw's shared media tools, use the comfy plugin together with an API key for cloud workflows.

Comfy Cloud with MCP OAuth

Register the hosted server, then sign in with your Comfy account:

openclaw mcp set comfy '{"url":"https://cloud.comfy.org/mcp","transport":"streamable-http","auth":"oauth"}'
openclaw mcp login comfy
openclaw mcp status --verbose

Open the authorization URL that login prints and follow the CLI prompts. When the browser is unable to reach the loopback callback, fall back to the printed --code. Callback handling, token refresh, and sign-in recovery are covered in the MCP OAuth workflow.

Once authorized, have your agent discover Comfy templates or generate media via the MCP tools. Generation on Comfy requires an active Cloud subscription. An optional OpenClaw skill is also documented in its MCP setup guide.

MCP credentials are stored on the https://cloud.comfy.org/mcp resource. Configuring this connection does not set up comfy/workflow, nor does it provide the workflow plugin's apiKey. Native cloud workflow API-key setup stays separate, as covered below. To remove the stored MCP credentials but keep the server definition, run openclaw mcp logout comfy.

Workflow plugin

For workflow-driven ComfyUI runs, install the official comfy plugin:

openclaw plugins install @openclaw/comfy-provider

When a Gateway is running, installation applies to it automatically; if not, it takes effect at the next startup. See Apply changes and inspect.

The plugin works purely from workflows: OpenClaw does not translate generic size, aspectRatio, resolution, durationSeconds, or TTS-style controls into your graph.

What it supports

• Generating and editing images from a workflow JSON (editing accepts 1 uploaded reference image)
• Generating video from a workflow JSON, either text-to-video or image-to-video (1 reference image)
• Generating music/audio via the shared music_generate tool, optionally with 1 reference image
• Downloading output from a configured node, or from every matching output node when none is configured

Getting started

You can either run ComfyUI on your own machine or use Comfy Cloud.

Local

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

Start ComfyUI locally

Confirm your local ComfyUI instance is running (the default is http://127.0.0.1:8188).

Prepare your workflow JSON

Create or export a ComfyUI workflow JSON file. Record the node IDs of the prompt input node and of the output node that OpenClaw should read from.

Configure the provider

Set mode: "local" and point it 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

For the capability you configured, point OpenClaw at the comfy/workflow model:

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "comfy/workflow",
        },
      },
    },
  },
}

Verify

openclaw models list --provider comfy

Comfy Cloud

Best for: running workflows on Comfy Cloud without having to manage local GPU resources.

Get an API key

Register at comfy.org and create an API key from your account dashboard.

Set the API key

Supply your key using 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"

Prepare your workflow JSON

Create or export a ComfyUI workflow JSON file. Record the node IDs of the prompt input node and the output node.

Configure the provider

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

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

Tip

In cloud mode, baseUrl defaults to https://cloud.comfy.org. Set baseUrl only when you need a custom cloud endpoint.

Set the default model

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "comfy/workflow",
        },
      },
    },
  },
}

Verify

openclaw models list --provider comfy

Configuration

Comfy accepts shared top-level connection settings, along with workflow sections for each capability (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

For a ComfyUI instance that sits behind HTTP authentication, use headers.Authorization. Credentials are best supplied through a secret reference. In both modes, headers apply to uploads, workflow submissions, polling, and downloads. They override the default headers without regard to case, with one exception: Content-Type on image uploads, where the multipart boundary is set by the runtime. If a header SecretRef cannot be resolved, the request fails before anything is sent. Response errors have reflected header values redacted.

Note

In local mode, single-label service names such as http://comfyui:8188 and loopback/private IP literals work without allowPrivateNetwork. A public-looking private-DNS FQDN such as https://comfy.local.example.com does require allowPrivateNetwork: true. Trust for private origins is limited to the configured scheme, hostname, and port: local redirects cannot leave the configured hostname, and cloud redirects to public CDNs are evaluated against the default SSRF policy.

Per-capability keys

The following keys are used within the image, video, or music sections:

A request timeout set explicitly wins over this configured default. A single timeout budget covers reference uploads, submission, polling, history, and every output download, response bodies included. When the timeout fires, local waiting stops; a job that was already submitted to ComfyUI is not cancelled.

A reference-image input node is also supported by the image and video sections:

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

Workflow details

Image workflows

To make comfy/workflow the default image model:

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "comfy/workflow",
        },
      },
    },
  },
}

Reference-image editing example:

Add inputImageNodeId to your image config to turn on editing with an uploaded reference image:

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

Video workflows

To make comfy/workflow the default video model:

{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "comfy/workflow",
        },
      },
    },
  },
}

Video workflows in Comfy handle text-to-video and image-to-video, driven by the graph you configure.

Note

Input videos are never passed into Comfy workflows by OpenClaw. The only accepted inputs are text prompts and a single reference image.

Music workflows

A music-generation provider is registered by the bundled plugin, covering audio or music outputs defined by a workflow and exposed via the shared music_generate tool. One optional reference image may be supplied (maximum of 1):

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

Point at your audio workflow JSON and its output node through the music config section.

Backward compatibility

The older top-level image config, which lacks the nested image section, remains functional:

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

That legacy shape is read by OpenClaw as the image workflow config. Migrating right away is not required, though for new setups the nested image / video / music sections are the recommended choice. When image generation is your only use case, the legacy flat config and the new nested image section behave the same in practice.

Live tests

Live coverage for the bundled plugin is opt-in:

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

Unless the corresponding Comfy workflow section is configured, the live test skips each image, video, or music case.

Related

• Image Generation, How to configure and use the image generation tool.

• Video Generation, How to configure and use the video generation tool.

• Music Generation, Setting up music and audio generation.

• Provider Directory, A survey of every provider and model ref.

• Configuration reference, The complete config reference, agent defaults included.