ComfyUI

OpenClaw 附带了一个捆绑的 comfy 插件，用于驱动工作流的 ComfyUI 运行。该插件完全由工作流驱动，因此 OpenClaw 不会尝试将通用的 size、aspectRatio、resolution、durationSeconds 或 TTS 风格的控制映射到您的图上。

属性	详情
提供商	comfy
模型	comfy/workflow
共享表面	image_generate、video_generate、music_generate
身份验证	本地 ComfyUI 不需要；Comfy Cloud 需要 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY
API	ComfyUI /prompt / /history / /view 以及 Comfy Cloud /api/*

支持内容

• 从工作流 JSON 生成图像
• 使用 1 张上传的参考图像进行图像编辑
• 从工作流 JSON 生成视频
• 使用 1 张上传的参考图像生成视频
• 通过共享的 music_generate 工具生成音乐或音频
• 从配置的节点或所有匹配的输出节点下载输出

入门指南

选择在您自己的机器上运行 ComfyUI 或使用 Comfy Cloud。

LocalComfy Cloud

最适用于： 在您的机器或局域网上运行您自己的 ComfyUI 实例。

1. Start ComfyUI locally

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

2. Prepare your workflow JSON

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

3. Configure the 提供商

   设置 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. Set the default 模型

   将 OpenClaw 指向您所配置功能的 comfy/workflow 模型：

   {
     agents: {
       defaults: {
         imageGenerationModel: {
           primary: "comfy/workflow",
         },
       },
     },
   }

5. Verify

   openclaw models list --provider comfy

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

1. 获取 API 密钥

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

2. 设置 API 密钥

   通过以下方法之一提供您的密钥：

   # 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"

3. 准备工作流 JSON

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

4. 配置提供商

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

   {
     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: {
         imageGenerationModel: {
           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"	连接模式。
baseUrl	string	本地默认为 http://127.0.0.1:8188，云端默认为 https://cloud.comfy.org。
apiKey	string	可选的内联键，是 COMFY_API_KEY / COMFY_CLOUD_API_KEY 环境变量的替代方案。
allowPrivateNetwork	boolean	允许在云模式下使用私有/LAN baseUrl。

各功能键

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

键	必需	默认	描述
workflow 或 workflowPath	是	—	ComfyUI 工作流 JSON 文件的路径。
promptNodeId	是	—	接收文本提示的节点 ID。
promptInputName	否	"text"	提示节点上的输入名称。
outputNodeId	否	—	读取输出的节点 ID。如果省略，则使用所有匹配的输出节点。
pollIntervalMs	否	—	轮询作业完成的间隔（毫秒）。
timeoutMs	否	—	工作流运行的超时时间（毫秒）。

image 和 video 部分也支持：

键	必需	默认	描述
inputImageNodeId	是（传递参考图片时）	—	接收上传参考图片的节点 ID。
inputImageInputName	否	"image"	图片节点上的输入名称。

工作流详细信息

图片工作流

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

{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "comfy/workflow",
      },
    },
  },
}

参考图片编辑示例：

要使用上传的参考图片启用图片编辑，请在图片配置中添加 inputImageNodeId：

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

视频工作流

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

{
  agents: {
    defaults: {
      videoGenerationModel: {
        primary: "comfy/workflow",
      },
    },
  },
}

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

Note

OpenClaw 不会将输入视频传递到 Comfy 工作流中。仅支持文本提示和单个参考图片作为输入。

音乐工作流

随附插件会为工作流定义的音频或音乐输出注册一个音乐生成提供商，并通过共享的 music_generate 工具来使用它：

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

使用 music 配置部分来指定您的音频工作流 JSON 和输出节点。

向后兼容性

现有的顶层图像配置（没有嵌套的 image 部分）仍然有效：

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

OpenClaw 会将这种旧版格式视为图像工作流配置。您无需立即迁移，但建议在新设置中使用嵌套的 image / video / music 部分。

Tip

如果您仅使用图像生成，旧的扁平配置和新的嵌套 image 部分在功能上是等效的。

实时测试

随附插件提供了可选的实时测试覆盖：

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

除非配置了匹配的 Comfy 工作流部分，否则实时测试会跳过单独的图像、视频或音乐用例。

相关内容

图像生成

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

视频生成

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

音乐生成

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

提供商目录

所有提供商和模型引用的概述。

配置参考

包括代理默认值的完整配置参考。