Use Comfy Cloud's hosted MCP server for account OAuth and Comfy's own discovery and generation tools. Use the comfy plugin for workflow-driven runs through Apus's shared media tools, with an API key for cloud workflows.

Comfy Cloud with MCP OAuth

Save the hosted server and sign in with your Comfy account:

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

Open the authorization URL printed by login and follow the CLI instructions. If the browser cannot reach the loopback callback, use the printed --code fallback. See the MCP OAuth workflow for callback, refresh, and sign-in recovery details.

After authorization, ask your agent to discover Comfy templates or generate media through the MCP tools. Comfy requires an active Cloud subscription for generation. Its MCP setup guide also documents an optional Apus skill.

MCP credentials belong to the https://cloud.comfy.org/mcp resource. This connection does not configure comfy/workflow or supply the workflow plugin's apiKey. Keep native cloud workflow API-key setup separate, as described below. To clear the stored MCP credentials while keeping the server definition, run apus mcp logout comfy.

Workflow plugin

Install the official comfy plugin for workflow-driven ComfyUI runs:

apus plugins install @openclaw/comfy-provider

Installation applies to a running Gateway automatically; otherwise it takes effect on the next startup. See Apply changes and inspect.

The plugin is entirely workflow-driven: Apus does not map generic size, aspectRatio, resolution, durationSeconds, or TTS-style controls onto your graph.

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.

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

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

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

    Set `mode: "local"` and point at your workflow file. 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",
              },
            },
          },
        },
      },
    }
    ```

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

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

    ```bash
    apus models list --provider comfy
    ```

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

    Sign up at [comfy.org](https://comfy.org) and generate an API key from your account dashboard.

    Provide your key through any of these methods:

    ```bash
    # Onboarding flag
    apus 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
    apus config set plugins.entries.comfy.config.apiKey "your-key"
    ```

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

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

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

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

    ```bash
    apus 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

Use headers.Authorization for a ComfyUI instance behind HTTP authentication. Prefer a secret reference for credentials. Headers apply to uploads, workflow submissions, polling, and downloads in both modes. They override default headers case-insensitively, except Content-Type on image uploads: the runtime sets the multipart boundary. An unavailable header SecretRef fails before any request is sent. Reflected header values are redacted from response errors.

Per-capability keys

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

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

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

Workflow details

Set the default image model to `comfy/workflow`:

```json5
{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          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",
          },
        },
      },
    },
  },
}
```

Set the default video model to `comfy/workflow`:

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

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

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

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):

```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.

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

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

Apus 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.

Opt-in live coverage exists for the bundled plugin:

```bash
APUS_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 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.