快速开始
ComfyUI
OpenClaw 内置了一个用于工作流驱动型 ComfyUI 运行的 comfy 插件。该插件完全由工作流驱动：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工具生成音乐/音频，可选择提供 1 张参考图像 - 从配置的节点下载输出；未配置节点时，从所有匹配的输出节点下载
入门指南
选择在自己的计算机上运行 ComfyUI，或使用 Comfy Cloud。
Local
**最适合：**在你的计算机或局域网上运行自己的 ComfyUI 实例。
Start ComfyUI locally
确保你的本地 ComfyUI 实例正在运行（默认为 http://127.0.0.1:8188）。
Prepare your workflow JSON
导出或创建 ComfyUI 工作流 JSON 文件。记下提示词输入节点以及希望 OpenClaw 读取的输出节点的节点 ID。
Configure the provider
设置 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", }, }, }, }, },}Set the default model
为你配置的能力将 OpenClaw 指向 comfy/workflow 模型：
{ agents: { defaults: { imageGenerationModel: { primary: "comfy/workflow", }, }, },}Verify
openclaw models list --provider comfyComfy Cloud
**最适合：**在无需管理本地 GPU 资源的情况下，通过 Comfy Cloud 运行工作流。
Get an API key
在 comfy.org 注册，并通过你的账户控制面板生成 API key。
Set the API key
通过以下任一方式提供你的密钥：
# 新手引导标志openclaw onboard --comfy-api-key "your-key" # 环境变量（守护进程的首选方式）export COMFY_API_KEY="your-key" # 备用环境变量export COMFY_CLOUD_API_KEY="your-key" # 或在配置中内联设置openclaw config set plugins.entries.comfy.config.apiKey "your-key"Prepare your workflow JSON
导出或创建 ComfyUI 工作流 JSON 文件。记下提示词输入节点和输出节点的节点 ID。
Configure the provider
设置 mode: "cloud" 并指向你的工作流文件：
{ plugins: { entries: { comfy: { config: { mode: "cloud", image: { workflowPath: "./workflows/flux-api.json", promptNodeId: "6", outputNodeId: "9", }, }, }, }, },}Set the default model
{ agents: { defaults: { imageGenerationModel: { primary: "comfy/workflow", }, }, },}Verify
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 |
字符串 | 可选的内联密钥，可替代 COMFY_API_KEY / COMFY_CLOUD_API_KEY 环境变量。 |
allowPrivateNetwork |
布尔值 | 在云端模式下允许使用私有网络/局域网 baseUrl，或允许本地私有 DNS FQDN。 |
按能力配置的键
这些键适用于 image、video 或 music 配置段：
| 键 | 必需 | 默认值 | 描述 |
|---|---|---|---|
workflow 或 workflowPath |
是 | -- | 内联工作流 JSON，或 ComfyUI 工作流 JSON 文件的路径。 |
promptNodeId |
是 | -- | 接收文本提示词的节点 ID。 |
promptInputName |
否 | "text" |
提示词节点上的输入名称。 |
outputNodeId |
否 | -- | 要从中读取输出的节点 ID。省略时，将使用所有匹配的输出节点。 |
pollIntervalMs |
否 | 1500 |
轮询作业是否完成的时间间隔，以毫秒为单位。 |
timeoutMs |
否 | 300000 |
工作流运行的超时时间，以毫秒为单位。 |
image 和 video 配置段还支持参考图像输入节点：
| 键 | 必需 | 默认值 | 描述 |
|---|---|---|---|
inputImageNodeId |
是（传入参考图像时） | -- | 接收上传参考图像的节点 ID。 |
inputImageInputName |
否 | "image" |
图像节点上的输入名称。 |
apiKey 接受字面量字符串或机密引用对象。
工作流详情
Image workflows
将默认图像模型设置为 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", }, }, }, }, },}Video workflows
将默认视频模型设置为 comfy/workflow：
{ agents: { defaults: { videoGenerationModel: { primary: "comfy/workflow", }, }, },}Comfy 视频工作流通过配置的图支持文本生成视频和图像生成视频。
Music workflows
内置插件为工作流定义的音频或音乐输出注册了一个音乐生成提供商，并通过共享的 music_generate 工具提供该功能。它接受可选的参考图像（最多 1 张）：
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"使用 music 配置段指向你的音频工作流 JSON 和输出节点。
Backward compatibility
现有的顶层图像配置（不含嵌套的 image 配置段）仍然有效：
{ plugins: { entries: { comfy: { config: { workflowPath: "./workflows/flux-api.json", promptNodeId: "6", outputNodeId: "9", }, }, }, },}OpenClaw 会将该旧版结构视为图像工作流配置。你不需要立即迁移，但对于新设置，建议使用嵌套的 image / video / music 配置段。如果你只使用图像生成，则旧版扁平配置与新的嵌套 image 配置段在功能上等效。
Live tests
内置插件提供了可选择启用的实时测试覆盖：
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts除非已配置对应的 Comfy 工作流部分，否则实时测试会跳过单独的图像、视频或音乐用例。
