---
read_when:
    - 你想在 OpenClaw 中使用本地 ComfyUI 工作流
    - 你想将 Comfy Cloud 与图像、视频或音乐工作流一起使用
    - 你需要内置 comfy 插件的配置键名
summary: OpenClaw 中的 ComfyUI 工作流图像、视频和音乐生成设置
title: ComfyUI
x-i18n:
    generated_at: "2026-04-12T10:12:23Z"
    model: gpt-5.4
    provider: openai
    source_hash: 85db395b171f37f80b34b22f3e7707bffc1fd9138e7d10687eef13eaaa55cf24
    source_path: providers/comfy.md
    workflow: 15
---

# ComfyUI

OpenClaw 附带了一个内置的 `comfy` 插件，用于基于工作流的 ComfyUI 运行。该插件完全由工作流驱动，因此 OpenClaw 不会尝试将通用的 `size`、`aspectRatio`、`resolution`、`durationSeconds` 或类似 TTS 的控制映射到你的图中。

| Property        | Detail                                                                              |
| --------------- | ----------------------------------------------------------------------------------- |
| Provider        | `comfy`                                                                             |
| Models          | `comfy/workflow`                                                                    |
| Shared surfaces | `image_generate`、`video_generate`、`music_generate`                                |
| Auth            | 本地 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。

<Tabs>
  <Tab title="Local">
    **最适合：** 在你的机器或 LAN 上运行你自己的 ComfyUI 实例。

    <Steps>
      <Step title="在本地启动 ComfyUI">
        确保你的本地 ComfyUI 实例正在运行（默认地址为 `http://127.0.0.1:8188`）。
      </Step>
      <Step title="准备你的工作流 JSON">
        导出或创建一个 ComfyUI 工作流 JSON 文件。记下提示词输入节点以及你希望 OpenClaw 读取的输出节点的节点 ID。
      </Step>
      <Step title="配置提供商">
        设置 `mode: "local"` 并指向你的工作流文件。以下是一个最小图像示例：

        ```json5
        {
          models: {
            providers: {
              comfy: {
                mode: "local",
                baseUrl: "http://127.0.0.1:8188",
                image: {
                  workflowPath: "./workflows/flux-api.json",
                  promptNodeId: "6",
                  outputNodeId: "9",
                },
              },
            },
          },
        }
        ```
      </Step>
      <Step title="设置默认模型">
        将 OpenClaw 指向你所配置能力对应的 `comfy/workflow` 模型：

        ```json5
        {
          agents: {
            defaults: {
              imageGenerationModel: {
                primary: "comfy/workflow",
              },
            },
          },
        }
        ```
      </Step>
      <Step title="验证">
        ```bash
        openclaw models list --provider comfy
        ```
      </Step>
    </Steps>

  </Tab>

  <Tab title="Comfy Cloud">
    **最适合：** 在无需管理本地 GPU 资源的情况下，在 Comfy Cloud 上运行工作流。

    <Steps>
      <Step title="获取 API 密钥">
        在 [comfy.org](https://comfy.org) 注册，并从你的账户仪表板生成 API 密钥。
      </Step>
      <Step title="设置 API 密钥">
        通过以下任一方式提供你的密钥：

        ```bash
        # 环境变量（推荐）
        export COMFY_API_KEY="your-key"

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

        # 或直接写入配置
        openclaw config set models.providers.comfy.apiKey "your-key"
        ```
      </Step>
      <Step title="准备你的工作流 JSON">
        导出或创建一个 ComfyUI 工作流 JSON 文件。记下提示词输入节点和输出节点的节点 ID。
      </Step>
      <Step title="配置提供商">
        设置 `mode: "cloud"` 并指向你的工作流文件：

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

        <Tip>
        云模式下，`baseUrl` 默认是 `https://cloud.comfy.org`。只有在你使用自定义云端点时，才需要设置 `baseUrl`。
        </Tip>
      </Step>
      <Step title="设置默认模型">
        ```json5
        {
          agents: {
            defaults: {
              imageGenerationModel: {
                primary: "comfy/workflow",
              },
            },
          },
        }
        ```
      </Step>
      <Step title="验证">
        ```bash
        openclaw models list --provider comfy
        ```
      </Step>
    </Steps>

  </Tab>
</Tabs>

## 配置

Comfy 支持共享的顶层连接设置，以及按能力划分的工作流部分（`image`、`video`、`music`）：

```json5
{
  models: {
    providers: {
      comfy: {
        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",
        },
      },
    },
  },
}
```

### 共享键名

| Key                   | Type                   | Description                                                                               |
| --------------------- | ---------------------- | ----------------------------------------------------------------------------------------- |
| `mode`                | `"local"` or `"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` 部分内部：

| Key                          | Required | Default  | Description                                                      |
| ---------------------------- | -------- | -------- | ---------------------------------------------------------------- |
| `workflow` or `workflowPath` | Yes      | --       | ComfyUI 工作流 JSON 文件的路径。                                 |
| `promptNodeId`               | Yes      | --       | 接收文本提示词的节点 ID。                                        |
| `promptInputName`            | No       | `"text"` | 提示词节点上的输入名称。                                         |
| `outputNodeId`               | No       | --       | 用于读取输出的节点 ID。如果省略，则使用所有匹配的输出节点。      |
| `pollIntervalMs`             | No       | --       | 用于检查任务完成状态的轮询间隔（毫秒）。                         |
| `timeoutMs`                  | No       | --       | 工作流运行的超时时间（毫秒）。                                   |

`image` 和 `video` 部分还支持：

| Key                   | Required                             | Default   | Description                                 |
| --------------------- | ------------------------------------ | --------- | ------------------------------------------- |
| `inputImageNodeId`    | Yes (when passing a reference image) | --        | 接收上传参考图像的节点 ID。                 |
| `inputImageInputName` | No                                   | `"image"` | 图像节点上的输入名称。                      |

## 工作流详情

<AccordionGroup>
  <Accordion title="Image workflows">
    将默认图像模型设置为 `comfy/workflow`：

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

    **参考图像编辑示例：**

    若要启用基于上传参考图像的图像编辑，请在你的图像配置中添加 `inputImageNodeId`：

    ```json5
    {
      models: {
        providers: {
          comfy: {
            image: {
              workflowPath: "./workflows/edit-api.json",
              promptNodeId: "6",
              inputImageNodeId: "7",
              inputImageInputName: "image",
              outputNodeId: "9",
            },
          },
        },
      },
    }
    ```

  </Accordion>

  <Accordion title="Video workflows">
    将默认视频模型设置为 `comfy/workflow`：

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

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

    <Note>
    OpenClaw 不会将输入视频传入 Comfy 工作流。仅支持将文本提示词和单张参考图像作为输入。
    </Note>

  </Accordion>

  <Accordion title="Music workflows">
    该内置插件为基于工作流定义的音频或音乐输出注册了一个音乐生成提供商，并通过共享的 `music_generate` 工具对外提供：

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

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

  </Accordion>

  <Accordion title="Backward compatibility">
    现有的顶层图像配置（不含嵌套的 `image` 部分）仍然可用：

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

    OpenClaw 会将这种旧版结构视为图像工作流配置。你无需立即迁移，但对于新设置，建议使用嵌套的 `image` / `video` / `music` 部分。

    <Tip>
    如果你只使用图像生成功能，则旧版扁平配置与新的嵌套 `image` 部分在功能上等效。
    </Tip>

  </Accordion>

  <Accordion title="Live tests">
    该内置插件提供了可选启用的实时覆盖测试：

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

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

  </Accordion>
</AccordionGroup>

## 相关内容

<CardGroup cols={2}>
  <Card title="Image Generation" href="/zh-CN/tools/image-generation" icon="image">
    图像生成工具的配置与用法。
  </Card>
  <Card title="Video Generation" href="/zh-CN/tools/video-generation" icon="video">
    视频生成工具的配置与用法。
  </Card>
  <Card title="Music Generation" href="/zh-CN/tools/music-generation" icon="music">
    音乐和音频生成工具设置。
  </Card>
  <Card title="Provider Directory" href="/zh-CN/providers/index" icon="layers">
    所有提供商和模型引用的概览。
  </Card>
  <Card title="Configuration Reference" href="/zh-CN/gateway/configuration-reference#agent-defaults" icon="gear">
    完整配置参考，包括智能体默认值。
  </Card>
</CardGroup>
