跳转至

ComfyUI

使用 Comfy Cloud 托管的 MCP 服务器进行账户 OAuth 认证,并使用 Comfy 自身的发现与生成工具。通过 OpenClaw 的共享媒体工具,使用 comfy 插件进行由工作流驱动的运行,并配合 API 密钥用于云端工作流。

使用 MCP OAuth 连接 Comfy Cloud

保存托管的服务器,并使用你的 Comfy 账户登录:

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

打开由 login 打印的授权 URL,并按照 CLI 提示操作。 如果浏览器无法访问回环(loopback)回调,请使用打印的 --code 回退方法。 参见 MCP OAuth 工作流 了解回调、刷新和登录恢复的详细信息。

授权后,请让你的 agent 通过 MCP 工具发现 Comfy 模板或生成媒体。Comfy 需要有效的 Cloud 订阅才能进行生成。它的 MCP 设置指南 也记录了一个可选的 OpenClaw 技能。

MCP 凭据归属于 https://cloud.comfy.org/mcp 资源。此连接不会配置 comfy/workflow,也不会提供工作流插件的 apiKey。请按照下文所述,将原生云端工作流 API 密钥的设置保持独立。要清除已存储的 MCP 凭据但保留服务器定义,请运行 openclaw mcp logout comfy。

工作流插件

安装官方 comfy 插件,用于由工作流驱动的 ComfyUI 运行:

openclaw plugins install @openclaw/comfy-provider

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

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

属性 详情
提供商 comfy
模型 comfy/workflow
共享工具 image_generate, video_generate, music_generate
认证 可选 headers 用于本地 HTTP 认证;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。

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

1. 在本地启动 ComfyUI

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

2. 准备工作流 JSON

导出或创建 ComfyUI 工作流 JSON 文件。记下提示词输入节点和你要让 OpenClaw 读取的输出节点的节点 ID。

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. 设置默认模型

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

**6. 验证**

```bash
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。 凭据优先使用密钥引用。 请求头适用于两种模式下的上传、工作流提交、轮询和下载。它们会不区分大小写地覆盖默认请求头,但图像上传中的 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 部分内部:

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

image 和 video 部分还支持参考图像输入节点:

键 必填 默认值 描述
inputImageNodeId 是(传递参考图像时) -- 接收上传的参考图像的节点 ID。
inputImageInputName 否 "image" 图像节点上的输入名称。

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

工作流详情

图像工作流

将默认图像模型设置为 comfy/workflow:

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

参考图像编辑示例:

要使用上传的参考图像启用图像编辑,请在你的图像配置中添加 `inputImageNodeId`:

```json5
{
  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 工作流。仅支持文本提示词和单张参考图像作为输入。

音乐工作流

捆绑插件会为工作流定义的音频或音乐输出注册一个音乐生成提供商,并通过共享的 music_generate 工具暴露。它接受一个可选的参考图像(最多 1 张):

/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 部分。如果你只使用图像生成,旧版扁平配置和新的嵌套 image 部分在功能上是等价的。

实时测试

捆绑插件提供了可选的实时测试覆盖:

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

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

图像生成

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

视频生成

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

音乐生成

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

提供商目录

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

配置参考

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

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