ComfyUI

安装官方 comfy 插件，以支持工作流驱动的 ComfyUI 运行：

openclaw plugins install @openclaw/comfy-provider

安装操作会自动应用到正在运行的 Gateway；否则将在下次启动时生效。参见应用更改并检查。

该插件完全由工作流驱动：OpenClaw 不会将通用的 size、aspectRatio、resolution、durationSeconds 或 TTS 风格的控制映射到你的图上。

属性	详情
Provider	`comfy`
Model	`comfy/workflow`
Shared tools	`image_generate`, `video_generate`, `music_generate`
Auth	本地 HTTP 认证可选用 `headers`；云模式使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`
API	ComfyUI `/prompt` / `/history` / `/view`；Comfy Cloud `/api/*`

支持的功能¶

通过工作流 JSON 进行图像生成和编辑（编辑模式使用 1 张上传的参考图像）
通过工作流 JSON 进行视频生成，支持文本生成视频或图像生成视频（1 张参考图像）
通过共享的 music_generate 工具进行音乐/音频生成，可选用 1 张参考图像
从配置的输出节点下载结果；若未配置节点，则从所有匹配的输出节点下载

快速开始¶

你可以选择在自己的机器上运行 ComfyUI，或使用 Comfy Cloud。

本地Comfy Cloud

**适用场景：** 在你的机器或局域网上运行你自己的 ComfyUI 实例。

1. 在本地启动 ComfyUI

确保你的本地 ComfyUI 实例正在运行（默认地址为 http://127.0.0.1:8188）。

2. 准备工作流 JSON

导出或创建一个 ComfyUI 工作流 JSON 文件。记下提示词输入节点和输出节点的节点 ID，OpenClaw 将从这些节点读取数据。

3. 配置提供方

设置 mode: "local" 并指向你的工作流文件。最小图像示例：

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

4. 设置默认模型

将 OpenClaw 指向你为相应能力配置的 comfy/workflow 模型：

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

5. 验证

openclaw models list --provider comfy

**适用场景：** 在 Comfy Cloud 上运行工作流，无需管理本地 GPU 资源。

1. 获取 API 密钥

在 comfy.org 注册并从你的账户仪表板生成 API 密钥。

2. 设置 API 密钥

可通过以下任一方式提供你的密钥：

# 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. 准备工作流 JSON

导出或创建一个 ComfyUI 工作流 JSON 文件。记下提示词输入节点和输出节点的节点 ID。

4. 配置提供方

    设置 `mode: "cloud"` 并指向你的工作流文件：

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

Tip

云模式下 baseUrl 默认为 https://cloud.comfy.org。仅为自定义云端点设置 baseUrl。

5. 设置默认模型

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

6. 验证

openclaw models list --provider comfy

配置¶

Comfy 支持共享的顶级连接设置，以及按能力划分的工作流配置段（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",
          },
        },
      },
    },
  },
}

共享键¶

键	类型	描述
`mode`	`"local"` 或 `"cloud"`	连接模式。默认为 `"local"`。
`baseUrl`	字符串	本地模式默认为 `http://127.0.0.1:8188`，云端模式默认为 `https://cloud.comfy.org`。
`apiKey`	字符串或 SecretRef	可选的云端密钥，作为 `COMFY_API_KEY` / `COMFY_CLOUD_API_KEY` 环境变量的替代。
`allowPrivateNetwork`	布尔值	允许在云端模式下使用私有/局域网的 `baseUrl`，或允许本地的私有 DNS FQDN。
`headers`	对象	额外的请求头；每个值接受字符串或 SecretRef。

对于位于 HTTP 认证之后的 ComfyUI 实例，请使用 headers.Authorization。对于凭据，优先使用 secret 引用。在两种模式下，请求头都适用于上传、工作流提交、轮询和下载。它们以不区分大小写的方式覆盖默认请求头，但图片上传时的 Content-Type 除外：运行时负责设置 multipart 边界。如果某个请求头引用的 SecretRef 不可用，则在发送任何请求之前就会失败。响应错误中会隐去回显的请求头值。

Note

在 local 模式下，回环/私有 IP 字面量和单标签服务名（如 http://comfyui:8188）无需 allowPrivateNetwork 即可使用。看起来像公网的私有 DNS FQDN（如 https://comfy.local.example.com）需要设置 allowPrivateNetwork: true。私有来源信任仅限于所配置的协议、主机名和端口；本地重定向不能离开所配置的主机名，而指向公共 CDN 的云端重定向会按照默认 SSRF 策略进行检查。

各能力对应的键¶

这些键适用于 image、video 或 music 部分：

键（Key）	是否必填	默认值	描述（Description）
`workflow` 或 `workflowPath`	是	--	内联工作流 JSON，或 ComfyUI 工作流 JSON 文件的路径。
`promptNodeId`	是	--	接收文本提示的节点 ID。
`promptInputName`	否	`"text"`	提示节点上的输入名称。
`seedNodeId`	否	--	每次提交时其输入都会收到新的随机种子的节点 ID。省略则每次运行时都复用工作流文件中内置的种子。
`seedInputName`	否	`"seed"`	种子节点上的输入名称。
`outputNodeId`	否	--	从中读取输出的节点 ID。如果省略，则使用所有匹配的输出节点。
`pollIntervalMs`	否	`1500`	任务完成的轮询间隔（毫秒）。
`timeoutMs`	否	`300000`	工作流运行的超时时间（毫秒）。

image 和 video 部分还支持一个参考图片输入节点：

键（Key）	是否必填	默认值	描述（Description）
`inputImageNodeId`	是（当传递参考图片时）	--	接收上传的参考图片的节点 ID。
`inputImageInputName`	否	`"image"`	图片节点上的输入名称。

apiKey 接受字面字符串或 secret 引用对象。

工作流详情¶

图片工作流

将默认图片模型设置为 comfy/workflow：

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

参考图片编辑示例：

要使用上传的参考图片进行图片编辑，请将 inputImageNodeId 添加到你的图片配置中：

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

视频工作流

将默认视频模型设置为 `comfy/workflow`：

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

Comfy 视频工作流支持通过已配置的图实现文本生成视频和图像生成视频。

!!! note

    OpenClaw 不会将输入视频传入 Comfy 工作流。仅支持文本 Prompt 和单张参考图像作为输入。

音乐工作流

捆绑插件会为工作流定义的音频或音乐输出注册一个音乐生成 provider，并通过共享的 music_generate 工具暴露。它接受一个可选参考图像（最多 1 张）：

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

使用 music 配置段指向你的音频工作流 JSON 和输出节点。

向后兼容

现有的顶层 image 配置（没有嵌套的 image 段）仍然有效：

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

OpenClaw 会将该旧格式视为 image 工作流配置。你无需立即迁移，但新配置建议使用嵌套的 image / video / music 段。如果只使用图像生成，旧版扁平配置和新的嵌套 image 段在功能上是等价的。

实时测试

捆绑插件支持可选启用的实时测试覆盖：

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

除非配置了匹配的 Comfy 工作流段，否则实时测试会跳过单独的 image、video 或 music 用例。

图像生成

图像生成工具的配置和使用。

视频生成

视频生成工具的配置和使用。

音乐生成

音乐和音频生成工具的设置。

Provider 目录

所有 provider 和模型引用的概览。

配置参考

完整配置参考，包括 agent 默认值。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw