古法编程

Appearance

如果你在 OpenClaw 中使用 ComfyUI 工作流生成图片、视频或音乐，这篇文档引导你完成本地实例或 Comfy Cloud 的配置。核心操作是准备 workflow JSON、记下提示节点和输出节点 ID，然后在 plugins.entries.comfy.config 中填入 mode、workflowPath、promptNodeId 和可选的 outputNodeId。配置后用 openclaw models list --provider comfy 验证是否生效。comfy 插件完全由 workflow 驱动，不会自动映射通用参数（如尺寸、时长）。

OpenClaw ComfyUI 接入：本地与 Comfy Cloud 图像/视频/音乐生成配置 ​

OpenClaw 内置 comfy 插件，用于执行 ComfyUI 工作流。插件完全由 workflow 驱动，OpenClaw 不会将通用的 size、aspectRatio、resolution、durationSeconds 或 TTS 风格控制自动映射到你的 ComfyUI 图上。

属性说明
Provider IDcomfy
模型comfy/workflow
共享 Surfaceimage_generate、video_generate、music_generate
认证本地 ComfyUI 无需认证；Comfy Cloud 使用 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY
APIComfyUI /prompt / /history / /view 及 Comfy Cloud /api/*

支持的能力 ​

  • 从 workflow JSON 生成图片
  • 图片编辑，支持传入 1 张参考图片
  • 从 workflow JSON 生成视频
  • 视频生成，支持传入 1 张参考图片
  • 通过共享 music_generate 工具生成音乐或音频
  • 从指定输出节点或所有匹配的输出节点下载结果

怎么配置：本地 ComfyUI ​

适合在自己的机器或局域网中运行 ComfyUI。

步骤 ​

  1. 启动本地 ComfyUI：确保本机 ComfyUI 实例已运行（默认地址 http://127.0.0.1:8188）。
  2. 准备 workflow JSON：导出或创建 ComfyUI 工作流 JSON 文件。记下提示输入节点 ID 和期望输出节点 ID。
  3. 配置 provider：设置 mode: "local" 并指定 workflow 文件路径。以下是最简图片示例：
json5
{
  plugins: {
    entries: {
      comfy: {
        config: {
          mode: "local",
          baseUrl: "http://127.0.0.1:8188",
          image: {
            workflowPath: "./workflows/flux-api.json",
            promptNodeId: "6",
            outputNodeId: "9",
          },
        },
      },
    },
  },
}
  1. 设置默认模型：将 OpenClaw 的图片生成模型指向 comfy/workflow：
json5
{
  agents: {
    defaults: {
      imageGenerationModel: {
        primary: "comfy/workflow",
      },
    },
  },
}
  1. 验证：
bash
openclaw models list --provider comfy

怎么配置：Comfy Cloud ​

适合不管理本地 GPU，通过 Comfy Cloud 执行工作流。

步骤 ​

  1. 获取 API 密钥：在 comfy.org 注册并生成 API Key。
  2. 设置 API 密钥：通过环境变量或内联配置提供密钥。
bash
# 环境变量（推荐）
export COMFY_API_KEY="your-key"

# 备选环境变量
export COMFY_CLOUD_API_KEY="your-key"

# 或内联配置
openclaw config set plugins.entries.comfy.config.apiKey "your-key"
  1. 准备 workflow JSON：同本地版，导出并记下节点 ID。
  2. 配置 provider：设置 mode: "cloud" 并指定 workflow 文件。
json5
{
  plugins: {
    entries: {
      comfy: {
        config: {
          mode: "cloud",
          image: {
            workflowPath: "./workflows/flux-api.json",
            promptNodeId: "6",
            outputNodeId: "9",
          },
        },
      },
    },
  },
}

云模式下 baseUrl 默认指向 https://cloud.comfy.org，仅在使用自定义云端点时需显式设置。

  1. 设置默认模型：同上。
  2. 验证：
bash
openclaw models list --provider comfy

全部配置项 ​

Comfy 支持共享顶层连接设置，以及按能力划分的 workflow 区块（image、video、music）。

json5
{
  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"连接模式。
baseUrlstring本地默认 http://127.0.0.1:8188，云模式默认 https://cloud.comfy.org。
apiKeystring可选内联密钥，可替代 COMFY_API_KEY / COMFY_CLOUD_API_KEY 环境变量。
allowPrivateNetworkboolean允许在云模式下使用私有/LAN 的 baseUrl。

各能力区块配置键（用于 image、video、music） ​

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

image 和 video 区块额外支持：

键必填（传入参考图片时）默认值说明
inputImageNodeId是--接收上传参考图片的节点 ID。
inputImageInputName否"image"图片节点上的输入名称。

工作流详情 ​

图片工作流 ​

设置默认图片模型：

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

参考图片编辑示例：在图片配置中添加 inputImageNodeId：

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

视频工作流 ​

设置默认视频模型：

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

Comfy 视频工作流支持文生视频和图生视频，均通过配置的图实现。OpenClaw 不会将输入视频传入 Comfy 工作流，仅支持文本提示和单张参考图片作为输入。

音乐工作流 ​

内置插件注册了一个音乐生成 provider，通过共享 music_generate 工具暴露，用于 workflow 定义的音频或音乐输出：

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

在 music 配置区块中指向你的音频 workflow JSON 和输出节点。

向后兼容 ​

已有的顶层图片配置（未使用嵌套 image 区块）仍然可用：

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

OpenClaw 将这种旧写法视为图片工作流配置。如果你只使用图片生成，旧格式和新的嵌套 image 区块功能上等价。但新配置推荐使用嵌套分区。

集成测试 ​

可选启用插件集成测试：

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

集成测试会跳过未配置对应 Comfy 工作流区块的图片、视频或音乐用例。

常见问题 ​

Comfy 插件认证失败怎么办？ ​

本地模式无需认证。云模式需要提供 COMFY_API_KEY 或 COMFY_CLOUD_API_KEY 环境变量，或在配置中设置 apiKey。用 echo $COMFY_API_KEY 确认环境变量已正确设置。如果使用内联配置，执行 openclaw config get plugins.entries.comfy.config.apiKey 检查是否存入了值。

为什么 OpenClaw 不把 size、aspectRatio 等参数传给工作流？ ​

comfy 插件是 workflow 驱动的，它不会猜测如何将通用参数映射到你的自定义节点上。所有参数控制必须在 workflow JSON 内通过节点配置直接定义。OpenClaw 只负责传递文本提示和可选参考图片。

配置了 workflow 但生成没有输出怎么办？ ​

检查 outputNodeId 是否指向正确的节点。如果未设置 outputNodeId，插件会尝试所有匹配的输出节点，可能导致结果不符合预期。用 openclaw models list --provider comfy 确认 provider 已加载，并观察 OpenClaw 日志中是否有 comfy 相关的错误信息。

友情链接： 能跑吗 · 打工算 · 车主算 · 开发工具 · 人工不智能

Copyright © 2026 古法编程 | 蜀ICP备2021007188号 | 关于本站 | 隐私政策