{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Comfyui

使用 ComfyUI 生成图像、视频和音频——安装、启动、管理节点/模型、运行带参数注入的工作流。使用官方 comfy-cli 进行生命周期管理，使用直接 REST/WebSocket API 执行工作流。

Skill 元数据


来源	内置（默认安装）
路径	`skills/creative/comfyui`
版本	`5.1.0`
作者	['kshitijk4poor', 'alt-glitch', 'purzbeats']
许可证	MIT
平台	macos, linux, windows
标签	`comfyui`, `image-generation`, `stable-diffusion`, `flux`, `sd3`, `wan-video`, `hunyuan-video`, `creative`, `generative-ai`, `video-generation`
相关 skill	`stable-diffusion-image-generation`, `image_gen`

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时看到的指令内容。

ComfyUI

通过 ComfyUI 生成图像、视频、音频和 3D 内容，使用官方 comfy-cli 进行安装/生命周期管理，使用直接 REST/WebSocket API 执行工作流。

此 skill 包含的内容

参考文档（references/）：

official-cli.md — 所有 comfy ... 命令及其标志

rest-api.md — REST + WebSocket 端点（本地 + 云端），payload（载荷）schema

workflow-format.md — API 格式 JSON、常见节点类型、参数映射

template-integrity.md — 将 comfyui-workflow-templates 从编辑器格式转换为 API 格式：Reroute bypass、点分动态输入键（values.a、resize_type.width）、云端特性（302 重定向、免费层 1 个并发任务、1080p VRAM 上限）、Discord 兼容 ffmpeg 拼接。由 @purzbeats 撰写。从官方模板开始时请加载此文档。

脚本（scripts/）：

脚本	用途
`_common.py`	共享 HTTP、云端路由、节点目录（不要直接运行）
`hardware_check.py`	探测 GPU/VRAM/磁盘 → 推荐本地或 Comfy Cloud
`comfyui_setup.sh`	硬件检查 + comfy-cli + ComfyUI 安装 + 启动 + 验证
`extract_schema.py`	读取工作流 → 列出可控参数 + 模型依赖
`check_deps.py`	对比运行中的服务器检查工作流 → 列出缺失节点/模型
`auto_fix_deps.py`	运行 check_deps 然后执行 `comfy node install` / `comfy model download`
`run_workflow.py`	注入参数、提交、监控、下载输出（HTTP 或 WS）
`run_batch.py`	以 sweep 方式提交工作流 N 次，并行数量受限于你的套餐层级
`ws_monitor.py`	执行中任务的实时 WebSocket 查看器（实时进度）
`health_check.py`	验证清单运行器——comfy-cli + 服务器 + 模型 + 冒烟测试
`fetch_logs.py`	拉取指定 prompt_id 的 traceback / 状态消息

示例工作流（workflows/）： SD 1.5、SDXL、Flux Dev、SDXL img2img、SDXL inpaint、ESRGAN 放大、AnimateDiff 视频、Wan T2V。参见 workflows/README.md。

使用场景

用户要求使用 Stable Diffusion、SDXL、Flux、SD3 等生成图像

用户想运行特定的 ComfyUI 工作流文件

用户想串联生成步骤（txt2img → 放大 → 人脸修复）

用户需要 ControlNet、inpainting、img2img 或其他高级 pipeline

用户要管理 ComfyUI 队列、检查模型或安装自定义节点

用户想通过 AnimateDiff、Hunyuan、Wan、AudioCraft 等进行视频/音频/3D 生成

架构：两层

┌─────────────────────────────────────────────────────┐
│ Layer 1: comfy-cli (official lifecycle tool)        │
│   Setup, server lifecycle, custom nodes, models     │
│   → comfy install / launch / stop / node / model    │
└─────────────────────────┬───────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────┐
│ Layer 2: REST/WebSocket API + skill scripts         │
│   Workflow execution, param injection, monitoring   │
│   POST /api/prompt, GET /api/view, WS /ws           │
│   → run_workflow.py, run_batch.py, ws_monitor.py    │
└─────────────────────────────────────────────────────┘

为什么要两层？ 官方 CLI 非常适合安装和服务器管理，但对工作流执行的支持极少。REST/WS API 填补了这一空缺——脚本处理 CLI 不具备的参数注入、执行监控和输出下载功能。

快速开始

检测环境

如果未安装任何内容，请参阅下方的安装与引导——但始终先运行硬件检查。

一行健康检查

核心工作流

第一步：获取 API 格式的工作流 JSON

工作流必须为 API 格式（每个节点有 class_type）。来源包括：

ComfyUI Web UI → Workflow → Export (API)（新版 UI）或旧版"Save (API Format)"按钮（旧版 UI）

此 skill 的 workflows/ 目录（可直接运行的示例）

社区下载（civitai、Reddit、Discord）——通常为编辑器格式，必须加载到 ComfyUI 后重新导出

编辑器格式（顶层含 nodes 和 links 数组）不可直接执行。脚本会检测此情况并提示你重新导出。

第二步：查看可控内容

第三步：带参数运行

seed 传 -1（或配合 --randomize-seed 省略 seed）可在每次运行时生成新的随机种子。

第四步：呈现结果

脚本向 stdout 输出描述每个输出文件的 JSON：

{
  "status": "success",
  "prompt_id": "abc-123",
  "outputs": [
    {"file": "./outputs/sdxl_00001_.png", "node_id": "9",
     "type": "image", "filename": "sdxl_00001_.png"}
  ]
}

决策树

用户说	工具	命令
生命周期（使用 comfy-cli）
"安装 ComfyUI"	comfy-cli	`bash scripts/comfyui_setup.sh`
"启动 ComfyUI"	comfy-cli	`comfy launch --background`
"停止 ComfyUI"	comfy-cli	`comfy stop`
"安装 X 节点"	comfy-cli	`comfy node install <name>`
"下载 X 模型"	comfy-cli	`comfy model download --url <url> --relative-path models/checkpoints`
"列出已安装模型"	comfy-cli	`comfy model list`
"列出已安装节点"	comfy-cli	`comfy node show installed`
执行（使用脚本）
"一切准备好了吗？"	脚本	`health_check.py`（可选加 `--workflow X --smoke-test`）
"这个工作流我能改什么？"	脚本	`extract_schema.py W.json`
"检查 W 的依赖是否满足"	脚本	`check_deps.py W.json`
"修复缺失依赖"	脚本	`auto_fix_deps.py W.json`
"生成一张图片"	脚本	`run_workflow.py --workflow W --args '{...}'`
"使用这张图片"（img2img）	脚本	`run_workflow.py --input-image image=./x.png ...`
"8 个随机种子变体"	脚本	`run_batch.py --count 8 --randomize-seed ...`
"显示实时进度"	脚本	`ws_monitor.py --prompt-id <id>`
"获取任务 X 的错误"	脚本	`fetch_logs.py <prompt_id>`
直接 REST
"队列里有什么？"	REST	`curl http://HOST:8188/queue`（本地）或 `--host https://cloud.comfy.org`
"取消那个"	REST	`curl -X POST http://HOST:8188/interrupt`
"释放 GPU 内存"	REST	`curl -X POST http://HOST:8188/free`

安装与引导

当用户要求安装 ComfyUI 时，首先要询问他们想要 Comfy Cloud（托管，零安装，API key）还是本地安装（在其机器上安装 ComfyUI）。在得到答复之前，不要开始运行安装命令或硬件检查。

官方文档： https://docs.comfy.org/installation
CLI 文档： https://docs.comfy.org/comfy-cli/getting-started
Cloud 文档： https://docs.comfy.org/get_started/cloud
Cloud API： https://docs.comfy.org/development/cloud/overview

第零步：询问本地还是云端（始终优先）

建议话术：

"您想在本地机器上运行 ComfyUI，还是使用 Comfy Cloud？
Comfy Cloud — 托管于 RTX 6000 Pro GPU，所有常用模型预装，零配置。需要 API key（实际运行工作流需要付费订阅；免费层仅限只读）。如果您没有性能足够的 GPU，推荐此选项。
本地 — 免费，但您的机器必须满足硬件要求：
NVIDIA GPU，≥6 GB VRAM（SDXL 需 ≥8 GB，Flux/视频需 ≥12 GB），或
支持 ROCm 的 AMD GPU（Linux），或
Apple Silicon Mac（M1+），≥16 GB 统一内存（推荐 ≥32 GB）。
Intel Mac 和无 GPU 的机器不可用——请改用 Cloud。
您选择哪种？"

路由逻辑：

Cloud → 跳至路径 A。

本地 → 先运行硬件检查，再根据结果从路径 B–E 中选择。

不确定 → 运行硬件检查，由结果决定。

第一步：验证硬件（仅当用户选择本地时）

结果	含义	操作
`ok`	≥8 GB VRAM（独立显卡）或 ≥32 GB 统一内存（Apple Silicon）	本地安装——使用报告中的 `comfy_cli_flag`
`marginal`	SD1.5 可用；SDXL 较紧张；Flux/视频不太可能	轻量工作流可本地，否则选路径 A（Cloud）
`cloud`	无可用 GPU、<6 GB VRAM、<16 GB Apple 统一内存、Intel Mac、Rosetta Python	切换至 Cloud，除非用户明确强制本地

脚本还会显示 wsl: true（带 NVIDIA 直通的 WSL2）和 rosetta: true（Apple Silicon 上的 x86_64 Python——必须重新安装为 ARM64）。

如果结果为 cloud 但用户想要本地，不要静默继续。逐字显示 notes 数组，并询问他们是否要（a）切换至 Cloud 或（b）强制本地安装（在现代模型上会 OOM 或极慢）。

选择安装路径

优先使用硬件检查结果。下表适用于用户已告知其硬件的情况：

情况	推荐路径
硬件检查结果为 `verdict: cloud`	路径 A：Comfy Cloud
无 GPU / 想先试用	路径 A：Comfy Cloud
Windows + NVIDIA + 非技术用户	路径 B：ComfyUI Desktop
Windows + NVIDIA + 技术用户	路径 C：Portable 或路径 D：comfy-cli
Linux + 任意 GPU	路径 D：comfy-cli（最简单）
macOS + Apple Silicon	路径 B：Desktop 或路径 D：comfy-cli
无头/服务器/CI/agent	路径 D：comfy-cli

全自动路径（硬件检查 → 安装 → 启动 → 验证）：

该脚本内部运行 hardware_check.py，当结果为 cloud 时拒绝本地安装（除非传入 --force-cloud-override），选择正确的 comfy-cli 标志，并优先使用 pipx/uvx 而非全局 pip 以避免污染系统 Python。

路径 A：Comfy Cloud（无需本地安装）

适用于没有性能足够 GPU 或想要零配置的用户。托管于 RTX 6000 Pro。

文档： https://docs.comfy.org/get_started/cloud

在 https://comfy.org/cloud 注册

在 https://platform.comfy.org/login 生成 API key

设置 key：

运行工作流：

定价： https://www.comfy.org/cloud/pricing
并发任务： 免费/标准版 1 个，Creator 3 个，Pro 5 个。免费层无法通过 API 运行工作流——仅可浏览模型。/api/prompt、/api/upload/*、/api/view 等需要付费订阅。

路径 B：ComfyUI Desktop（Windows / macOS）

面向非技术用户的一键安装程序。目前为 Beta 版。

文档： https://docs.comfy.org/installation/desktop

Windows（NVIDIA）： https://download.comfy.org/windows/nsis/x64

macOS（Apple Silicon）： https://comfy.org

Linux 不支持 Desktop——请使用路径 D。

路径 C：ComfyUI Portable（仅 Windows）

文档： https://docs.comfy.org/installation/comfyui_portable_windows

从 https://github.com/comfyanonymous/ComfyUI/releases 下载，解压后运行 run_nvidia_gpu.bat。通过 update/update_comfyui_stable.bat 更新。

路径 D：comfy-cli（全平台——推荐用于 Agent）

官方 CLI 是无头/自动化安装的最佳路径。

文档： https://docs.comfy.org/comfy-cli/getting-started

安装 comfy-cli

非交互式禁用分析：

安装 ComfyUI

默认位置：~/comfy/ComfyUI（Linux），~/Documents/comfy/ComfyUI（macOS/Win）。使用 comfy --workspace /custom/path install 覆盖。

启动 / 验证

路径 E：手动安装（高级 / 不支持的硬件）

适用于昇腾 NPU、寒武纪 MLU、Intel Arc 或其他不支持的硬件。

文档： https://docs.comfy.org/installation/manual_install

安装后：下载模型

列出已安装：comfy model list。

安装后：安装自定义节点

安装后：验证

图像上传（img2img / Inpainting）

最简单的方式是在 run_workflow.py 中使用 --input-image：

该标志上传 photo.png，然后将其服务端文件名注入到 schema 中名为 image 的参数。对于 inpainting，同时传入：

通过 REST 手动上传：

云端特性

Base URL： https://cloud.comfy.org

认证： X-API-Key 请求头（WebSocket 使用 ?token=KEY）

API key： 设置一次 $COMFY_CLOUD_API_KEY，脚本自动读取

输出下载： /api/view 返回 302 跳转至签名 URL；脚本会跟随跳转并在从存储后端（S3/CloudFront）获取前去除 X-API-Key（避免泄露 API key）。

与本地 ComfyUI 的端点差异：

/api/object_info、/api/queue、/api/userdata — 免费层返回 403；仅付费可用。

/history 在云端重命名为 /history_v2（脚本自动路由）。

/models/<folder> 在云端重命名为 /experiment/models/<folder>（脚本自动路由）。

WebSocket 中的 clientId 目前被忽略——同一用户的所有连接接收相同广播。请在客户端按 prompt_id 过滤。

上传时接受 subfolder 但会被忽略——云端使用扁平命名空间。

并发任务： 免费/标准版：1，Creator：3，Pro：5。超出部分自动排队。使用 run_batch.py --parallel N 充分利用你的套餐层级。

队列与系统管理

常见问题

必须使用 API 格式 — 所有脚本和 /api/prompt 端点均需要 API 格式的工作流 JSON。脚本会检测编辑器格式（顶层含 nodes 和 links 数组）并提示通过"Workflow → Export (API)"（新版 UI）或"Save (API Format)"（旧版 UI）重新导出。

服务器必须运行 — 所有执行操作都需要运行中的服务器。comfy launch --background 可启动服务器。通过 curl http://127.0.0.1:8188/system_stats 验证。

模型名称必须精确 — 区分大小写，包含文件扩展名。check_deps.py 会进行模糊匹配（含/不含扩展名和文件夹前缀），但工作流本身必须使用规范名称。使用 comfy model list 查看已安装内容。

缺少自定义节点 — "class_type not found" 表示所需节点未安装。check_deps.py 会报告需要安装哪个包；auto_fix_deps.py 会自动执行安装。

工作目录 — comfy-cli 会自动检测 ComfyUI workspace。如果命令报错"no workspace found"，请使用 comfy --workspace /path/to/ComfyUI <command> 或 comfy set-default /path/to/ComfyUI。

云端免费层 API 限制 — /api/prompt、/api/view、/api/upload/*、/api/object_info 在免费账户上均返回 403。health_check.py 和 check_deps.py 会优雅处理此情况并显示清晰提示。

视频/音频工作流超时 — 当输出节点为 VHS_VideoCombine、SaveVideo 等时自动检测；默认超时从 300 秒跳至 900 秒。可通过 --timeout 1800 显式覆盖。

输出文件名路径遍历 — 服务端提供的文件名会经过 safe_path_join 处理，拒绝任何试图逃出 --output-dir 的路径。请保留此保护——带自定义保存节点的工作流可能产生任意路径。

工作流 JSON 是任意代码 — 自定义节点运行 Python，因此提交未知工作流的信任风险与 eval 相同。运行来自不可信来源的工作流前请先检查。

10.

自动随机化种子 — 在 --args 中传入 seed: -1（或使用 --randomize-seed 并省略 seed）可在每次运行时获得新种子。实际种子会记录到 stderr。

11.

tracking 提示 — 首次运行 comfy 可能会提示分析选项。使用 comfy --skip-prompt tracking disable 非交互式跳过。comfyui_setup.sh 会自动处理此问题。

验证清单

使用 python3 scripts/health_check.py 一次性运行全部检查。手动检查：

hardware_check.py 结果为 ok，或用户明确选择了 Comfy Cloud

comfy --version 可用（或 uvx --from comfy-cli comfy --help）

curl http://HOST:PORT/system_stats 返回 JSON

comfy model list 显示至少一个 checkpoint（本地），或 /api/experiment/models/checkpoints 返回模型（云端）

工作流 JSON 为 API 格式

check_deps.py 报告 is_ready: true（或云端免费层仅显示 node_check_skipped）

用小型工作流测试运行完成；输出文件出现在 --output-dir 中

"Comfyui"

Comfyui#

Skill 元数据#

参考：完整 SKILL.md#

ComfyUI#

此 skill 包含的内容#

使用场景#

架构：两层#

快速开始#

检测环境#

一行健康检查#

核心工作流#

第一步：获取 API 格式的工作流 JSON#

第二步：查看可控内容#

第三步：带参数运行#

第四步：呈现结果#

决策树#

安装与引导#

第零步：询问本地还是云端（始终优先）#

第一步：验证硬件（仅当用户选择本地时）#

选择安装路径#

路径 A：Comfy Cloud（无需本地安装）#

路径 B：ComfyUI Desktop（Windows / macOS）#

路径 C：ComfyUI Portable（仅 Windows）#

路径 D：comfy-cli（全平台——推荐用于 Agent）#

安装 comfy-cli#

安装 ComfyUI#

启动 / 验证#

路径 E：手动安装（高级 / 不支持的硬件）#

安装后：下载模型#

安装后：安装自定义节点#

安装后：验证#

图像上传（img2img / Inpainting）#

云端特性#

队列与系统管理#

常见问题#

验证清单#

Comfyui

Skill 元数据

参考：完整 SKILL.md

ComfyUI

此 skill 包含的内容

使用场景

架构：两层

快速开始

检测环境

一行健康检查

核心工作流

第一步：获取 API 格式的工作流 JSON

第二步：查看可控内容

第三步：带参数运行

第四步：呈现结果

决策树

安装与引导

第零步：询问本地还是云端（始终优先）

第一步：验证硬件（仅当用户选择本地时）

选择安装路径

路径 A：Comfy Cloud（无需本地安装）

路径 B：ComfyUI Desktop（Windows / macOS）

路径 C：ComfyUI Portable（仅 Windows）

路径 D：comfy-cli（全平台——推荐用于 Agent）

安装 comfy-cli

安装 ComfyUI

启动 / 验证

路径 E：手动安装（高级 / 不支持的硬件）

安装后：下载模型

安装后：安装自定义节点

安装后：验证

图像上传（img2img / Inpainting）

云端特性

队列与系统管理

常见问题

验证清单