comfyui

ComfyUI

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

此技能包含的内容

参考文档（references/）：

• official-cli.md — 所有 comfy ... 命令及其标志
• rest-api.md — REST + WebSocket 端点（本地 + 云端）、载荷架构
• workflow-format.md — API 格式的 JSON、常见节点类型、参数映射
• template-integrity.md — 将 comfyui-workflow-templates 从编辑器格式转换为 API 格式：绕过 Reroute、点分隔的动态输入键（values.a、resize_type.width）、云端注意事项（302 重定向、免费层级仅支持 1 个并发任务、1080p 显存上限）、兼容 Discord 的 ffmpeg 拼接。 由 @purzbeats 编写。从官方模板开始时，请务必加载此文档。

脚本（scripts/）：

脚本	用途
_common.py	共享 HTTP、云端路由、节点目录（请勿直接运行）
hardware_check.py	检查 GPU/显存/磁盘 → 推荐本地或 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	使用参数扫描提交工作流 N 次，并行数上限取决于你的层级
ws_monitor.py	正在执行任务的实时 WebSocket 查看器（实时进度）
health_check.py	验证清单运行器 — comfy-cli + 服务 + 模型 + 冒烟测试
fetch_logs.py	获取指定 prompt_id 的回溯信息/状态消息

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

适用场景

• 用户要求使用 Stable Diffusion、SDXL、Flux、SD3 等生成图像
• 用户想要运行特定的 ComfyUI 工作流文件
• 用户想串联生成步骤（txt2img → 放大 → 人脸修复）
• 用户需要 ControlNet、局部重绘、img2img 或其他高级管线
• 用户要求管理 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 无法完成的参数注入、执行监控和输出下载。

快速开始

检测环境

# What's available?
command -v comfy >/dev/null 2>&1 && echo "comfy-cli: installed"
curl -s http://127.0.0.1:8188/system_stats 2>/dev/null && echo "server: running"

# Can this machine run ComfyUI locally? (GPU/VRAM/disk check)
python scripts/hardware_check.py

如果尚未安装任何内容，请参阅下方的设置与入门 — 但务必先运行硬件检查。

一行命令完成健康检查

python scripts/health_check.py
# → JSON: comfy_cli on PATH? server reachable? at least one checkpoint? smoke-test passes?

核心工作流

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

工作流必须采用 API 格式（每个节点都有 class_type）。可从以下位置获取：

• ComfyUI Web UI → 工作流 → 导出（API）（新版 UI），或 旧版 UI 中的“保存（API 格式）”按钮
• 此技能的 workflows/ 目录（可直接运行的示例）
• 社区下载内容（civitai、Reddit、Discord）— 通常为编辑器格式， 必须先载入 ComfyUI，再重新导出

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

第 2 步：查看可控参数

python scripts/extract_schema.py workflow_api.json --summary-only
# → {"parameter_count": 12, "has_negative_prompt": true, "has_seed": true, ...}

python scripts/extract_schema.py workflow_api.json
# → full schema with parameters, model deps, embedding refs

第 3 步：使用参数运行

# Local (defaults to http://127.0.0.1:8188)
python scripts/run_workflow.py \
  --workflow workflow_api.json \
  --args '{"prompt": "a beautiful sunset over mountains", "seed": -1, "steps": 30}' \
  --output-dir ./outputs

# Cloud (export API key once; uses correct /api routing automatically)
export COMFY_CLOUD_API_KEY="comfyui-..."
python scripts/run_workflow.py \
  --workflow workflow_api.json \
  --args '{"prompt": "..."}' \
  --host https://cloud.comfy.org \
  --output-dir ./outputs

# Real-time progress via WebSocket (requires `pip install websocket-client`)
python scripts/run_workflow.py \
  --workflow flux_dev.json \
  --args '{"prompt": "..."}' \
  --ws

# img2img / inpaint: pass --input-image to upload + reference automatically
python scripts/run_workflow.py \
  --workflow sdxl_img2img.json \
  --input-image image=./photo.png \
  --args '{"prompt": "make it watercolor", "denoise": 0.6}'

# Batch / sweep: 8 random seeds, parallel up to cloud tier limit
python scripts/run_batch.py \
  --workflow sdxl.json \
  --args '{"prompt": "abstract"}' \
  --count 8 --randomize-seed --parallel 3 \
  --output-dir ./outputs/batch

将 seed 设为 -1（或使用 --randomize-seed 时省略该参数），每次运行都会生成一个新的随机种子。

第 4 步：呈现结果

脚本会将描述每个输出文件的 JSON 写入 stdout：

{
  "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 '{...}'
“使用这张图像”（图生图）	脚本	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 密钥）还是本地运行（在他们的设备上安装 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

步骤 0：询问本地运行还是使用 Cloud（始终第一步）

建议话术：

“你想在自己的设备上本地运行 ComfyUI，还是使用 Comfy Cloud？

• Comfy Cloud — 由 RTX 6000 Pro GPU 托管，预装了所有常用模型，无需任何设置。需要 API 密钥（实际运行工作流需要付费订阅；免费套餐仅支持只读）。如果你没有性能足够的 GPU，这是最佳选择。
• 本地运行 — 免费，但你的设备必须满足硬件要求：
  • 配备 ≥6 GB 显存的 NVIDIA GPU（SDXL 需要 ≥8 GB，Flux/视频需要 ≥12 GB），或
  • 支持 ROCm 的 AMD GPU（Linux），或
  • 配备 ≥16 GB 统一内存的 Apple Silicon Mac（M1+）（建议 ≥32 GB）。
  • Intel Mac 和没有 GPU 的设备无法运行——请改用 Cloud。

你想选哪种？”

分流：

• Cloud → 跳转至 路径 A。
• 本地运行 → 先检查硬件，再根据检查结果从路径 B–E 中选择路径。
• 不确定 → 检查硬件，并根据检查结果决定。

步骤 1：验证硬件（仅当用户选择本地安装时）

python scripts/hardware_check.py --json
# Optional: also probe `torch` for actual CUDA/MPS:
python scripts/hardware_check.py --json --check-pytorch

判定结果	含义	操作
ok	≥8 GB 显存（独立显卡）或 ≥32 GB 统一内存（Apple Silicon）	本地安装 — 使用报告中的 comfy_cli_flag
marginal	SD1.5 可运行；SDXL 性能吃紧；Flux/视频很可能无法运行	本地安装可用于轻量工作流，否则选择 路径 A（云端）
cloud	没有可用 GPU、显存 <6 GB、Apple 统一内存 <16 GB、Intel Mac、Rosetta Python	切换到云端，除非用户明确坚持本地安装

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

如果判定结果为 cloud，但用户想要本地安装，请勿默默继续。 原样显示 notes 数组，并询问用户想要（a）切换到云端，还是（b）强制本地安装（在现代模型上会出现内存溢出或速度慢到无法使用）。

选择安装路径

先进行硬件检查。用户已告知硬件配置时，可参考下表：

情况	推荐路径
硬件检查结果为 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

对于全自动流程（硬件检查 → 安装 → 启动 → 验证）：

bash scripts/comfyui_setup.sh
# Or with overrides:
bash scripts/comfyui_setup.sh --m-series --port=8190 --workspace=/data/comfy

该流程会在内部运行 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

1. 在 https://comfy.org/cloud 注册
2. 在 https://platform.comfy.org/login 生成 API 密钥
3. 设置密钥：

   export COMFY_CLOUD_API_KEY="your-comfyui-key"
   

4. 运行工作流：

   python scripts/run_workflow.py \
     --workflow workflows/flux_dev_txt2img.json \
     --args '{"prompt": "..."}' \
     --host https://cloud.comfy.org \
     --output-dir ./outputs
   

定价： https://www.comfy.org/cloud/pricing 并发任务数： Free/Standard 为 1，Creator 为 3，Pro 为 5。Free 层级 无法通过 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

Desktop 不支持 Linux — 请使用路径 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

# Recommended:
pipx install comfy-cli
# Or use uvx without installing:
uvx --from comfy-cli comfy --help
# Or (if pipx/uvx unavailable):
pip install --user comfy-cli

以非交互方式禁用分析：

comfy --skip-prompt tracking disable

安装 ComfyUI

comfy --skip-prompt install --nvidia              # NVIDIA (CUDA)
comfy --skip-prompt install --amd                 # AMD (ROCm, Linux)
comfy --skip-prompt install --m-series            # Apple Silicon (MPS)
comfy --skip-prompt install --cpu                 # CPU only (slow)
comfy --skip-prompt install --nvidia --fast-deps  # uv-based dep resolution

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

启动 / 验证

comfy launch --background                       # background daemon on :8188
comfy launch -- --listen 0.0.0.0 --port 8190    # LAN-accessible custom port
curl -s http://127.0.0.1:8188/system_stats      # health check

---

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

适用于 Ascend NPU、Cambricon MLU、Intel Arc 或其他不受支持的硬件。

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

git clone https://github.com/comfyanonymous/ComfyUI.git
cd ComfyUI
pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
pip install -r requirements.txt
python main.py

---

安装后：下载模型

# SDXL (general purpose, ~6.5 GB)
comfy model download \
  --url "https://huggingface.co/stabilityai/stable-diffusion-xl-base-1.0/resolve/main/sd_xl_base_1.0.safetensors" \
  --relative-path models/checkpoints

# SD 1.5 (lighter, ~4 GB, good for 6 GB cards)
comfy model download \
  --url "https://huggingface.co/stable-diffusion-v1-5/stable-diffusion-v1-5/resolve/main/v1-5-pruned-emaonly.safetensors" \
  --relative-path models/checkpoints

# Flux Dev fp8 (smaller variant, ~12 GB)
comfy model download \
  --url "https://huggingface.co/Comfy-Org/flux1-dev/resolve/main/flux1-dev-fp8.safetensors" \
  --relative-path models/checkpoints

# CivitAI (set token first):
comfy model download \
  --url "https://civitai.com/api/download/models/128713" \
  --relative-path models/checkpoints \
  --set-civitai-api-token "YOUR_TOKEN"

列出已安装的模型：comfy model list。

安装后：安装自定义节点

comfy node install comfyui-impact-pack             # popular utility pack
comfy node install comfyui-animatediff-evolved     # video generation
comfy node install comfyui-controlnet-aux          # ControlNet preprocessors
comfy node install comfyui-essentials              # common helpers
comfy node update all
comfy node install-deps --workflow=workflow.json   # install everything a workflow needs

安装后：验证

python scripts/health_check.py
# → comfy_cli on PATH? server reachable? checkpoints? smoke test?

python scripts/check_deps.py my_workflow.json
# → are this workflow's nodes/models/embeddings installed?

python scripts/run_workflow.py \
  --workflow workflows/sd15_txt2img.json \
  --args '{"prompt": "test", "steps": 4}' \
  --output-dir ./test-outputs

上传图像（img2img / 局部重绘）

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

python scripts/run_workflow.py \
  --workflow workflows/sdxl_img2img.json \
  --input-image image=./photo.png \
  --args '{"prompt": "make it cyberpunk", "denoise": 0.6}'

此标志会上传 photo.png，然后将其服务器端文件名注入到名为 image 的架构参数中。对于局部重绘，请同时传入：

python scripts/run_workflow.py \
  --workflow workflows/sdxl_inpaint.json \
  --input-image image=./photo.png \
  --input-image mask_image=./mask.png \
  --args '{"prompt": "fill with flowers"}'

通过 REST 手动上传：

curl -X POST "http://127.0.0.1:8188/upload/image" \
  -F "[email protected]" -F "type=input" -F "overwrite=true"
# Returns: {"name": "photo.png", "subfolder": "", "type": "input"}

# Cloud equivalent:
curl -X POST "https://cloud.comfy.org/api/upload/image" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
  -F "[email protected]" -F "type=input" -F "overwrite=true"

云端特性

• 基础 URL： https://cloud.comfy.org
• 身份验证： X-API-Key 标头（或 WebSocket 使用 ?token=KEY）
• API 密钥： 设置一次 $COMFY_CLOUD_API_KEY，脚本便会自动读取
• 下载输出： /api/view 会返回指向签名 URL 的 302 响应；脚本会跟随该响应，并在从存储后端获取文件前移除 X-API-Key（不要将 API 密钥泄露给 S3/CloudFront）。
• 与本地 ComfyUI 的端点差异：
  • /api/object_info、/api/queue、/api/userdata — 免费套餐会返回 403；仅限付费用户使用。
  • 云端将 /history 重命名为 /history_v2（脚本会自动路由）。
  • 云端将 /models/<folder> 重命名为 /experiment/models/<folder>（脚本会自动路由）。
  • WebSocket 中的 clientId 目前会被忽略 — 用户的所有连接都会收到相同的广播。请在客户端按 prompt_id 进行筛选。
  • 上传时接受 subfolder，但会忽略该参数 — 云端使用扁平命名空间。
• 并发任务： Free/Standard：1 个，Creator：3 个，Pro：5 个。额外任务会自动排队。使用 run_batch.py --parallel N 以充分利用套餐额度。

队列与系统管理

# Local
curl -s http://127.0.0.1:8188/queue | python -m json.tool
curl -X POST http://127.0.0.1:8188/queue -d '{"clear": true}'    # cancel pending
curl -X POST http://127.0.0.1:8188/interrupt                      # cancel running
curl -X POST http://127.0.0.1:8188/free \
  -H "Content-Type: application/json" \
  -d '{"unload_models": true, "free_memory": true}'

# Cloud — same paths under /api/, plus:
python scripts/fetch_logs.py --tail-queue --host https://cloud.comfy.org

常见问题

1. 必须使用 API 格式 — 每个脚本和 /api/prompt 端点都需要 API 格式的工作流 JSON。脚本会检测编辑器格式（顶层的 nodes 和 links 数组），并提示你通过“工作流 → 导出（API）”（新版 UI）或“保存（API 格式）”（旧版 UI）重新导出。

2. 服务必须正在运行 — 所有执行操作都需要有正在运行的服务。comfy launch --background 会启动服务。使用 curl http://127.0.0.1:8188/system_stats 验证。

3. 模型名称必须完全匹配 — 区分大小写，且包含文件扩展名。check_deps.py 会进行模糊匹配（检查是否带有扩展名和文件夹前缀），但工作流本身必须使用规范名称。使用 comfy model list 查看已安装的模型。

4. 缺少自定义节点 — “class_type not found” 表示未安装所需节点。check_deps.py 会报告需要安装哪个软件包；auto_fix_deps.py 会为你执行安装。

5. 工作目录 — comfy-cli 会自动检测 ComfyUI 工作区。如果命令因“no workspace found”而失败，请使用 comfy --workspace /path/to/ComfyUI <command> 或 comfy set-default /path/to/ComfyUI。

6. 云端免费套餐的 API 限制 — 免费账户调用 /api/prompt、/api/view、/api/upload/*、/api/object_info 都会返回 403。health_check.py 和 check_deps.py 会妥善处理此情况并显示清晰的提示。

7. 视频／音频工作流超时设置 — 当输出节点为 VHS_VideoCombine、SaveVideo 等时，会自动检测并将默认超时时间从 300 s 调至 900 s。可通过 --timeout 1800 显式覆盖。

8. 输出文件名中的路径遍历 — 服务端提供的文件名会经过 safe_path_join 处理，拒绝任何超出 --output-dir 的路径。请保持此保护启用 — 使用自定义保存节点的工作流可能会生成任意路径。

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

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

11. tracking 提示 — 首次运行 comfy 时可能会提示你启用分析功能。使用 comfy --skip-prompt tracking disable 可跳过提示并以非交互方式禁用分析。comfyui_setup.sh 会为你执行此操作。

验证清单

使用 python 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 显示至少一个检查点（本地），或 /api/experiment/models/checkpoints 返回模型（云端）
• 工作流 JSON 为 API 格式
• check_deps.py 报告 is_ready: true（或在云端免费套餐下仅报告 node_check_skipped）
• 使用小型工作流的测试运行成功完成；输出文件位于 --output-dir