{/* 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

通过扩散工作流生成图片、视频和音频。

Skill 元数据

参考：完整 SKILL.md

ComfyUI

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

本 skill 包含什么

参考文档（references/）：

• official-cli.md —— 每条 comfy ... 命令及其标志
• rest-api.md —— REST + WebSocket 端点（本地 + 云端）、负载 schema
• workflow-format.md —— API 格式 JSON、常见节点类型、参数映射
• template-integrity.md —— 把 comfyui-workflow-templates 从编辑器格式转成 API 格式：Reroute 旁路、点号动态输入键（values.a、resize_type.width）、云端怪癖（302 重定向、免费档 1 个并发任务、1080p VRAM 上限）、Discord 兼容的 ffmpeg 拼接。作者 @purzbeats。凡从官方模板起步都加载它。

脚本（scripts/）：

示例工作流（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 或其他高级管线
• 用户要求管理 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 → Workflow → Export (API)（较新 UI）或旧版的 "Save (API Format)" 按钮（较旧 UI）
• 本 skill 的 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 步：展示结果

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

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

决策表

安装与上手引导

当用户要求设置 ComfyUI 时，第一件事是问他们要 Comfy Cloud（托管、零安装、API key）还是 Local（在自己机器上装 ComfyUI）。在他们回答之前，不要开始跑安装命令或硬件检查。

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

第 0 步：问本地还是云端（永远先做）

建议话术：

"你想在自己机器上本地跑 ComfyUI，还是用 Comfy Cloud？

• Comfy Cloud —— 托管在 RTX 6000 Pro GPU 上，所有常用模型预装，零设置。需要 API key（真正跑工作流要付费订阅；免费档只读）。没有像样 GPU 时最佳。
• Local —— 免费，但你的机器必须满足硬件要求：
  • 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 → 跳到 路径 A。
• Local → 先跑硬件检查，再根据结论从路径 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

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

若结论是 cloud 但用户想要本地，不要静默继续。逐字展示 notes 数组，问他们是想 (a) 改用云端，还是 (b) 强制本地安装（在现代模型上会 OOM 或慢到没法用）。

选择安装路径

先跑硬件检查。下表是用户已告诉你硬件时的回退方案：

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

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 key
3. 设置 key：

   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 并发任务： 免费/Standard 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

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 / Inpainting）

最简单的方式是给 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 的 schema 参数。inpainting 时两个都传：

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 "image=@photo.png" -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 "image=@photo.png" -F "type=input" -F "overwrite=true"

云端细节

• Base URL： https://cloud.comfy.org
• 鉴权： X-API-Key 头（或 WebSocket 用 ?token=KEY）
• API key： 设置一次 $COMFY_CLOUD_API_KEY，脚本自动读取
• 输出下载： /api/view 返回 302 跳转到一个签名 URL；脚本跟随它，并在从存储后端抓取前去掉 X-API-Key（别把 API key 泄露给 S3/CloudFront）。
• 与本地 ComfyUI 的端点差异：
  • /api/object_info、/api/queue、/api/userdata —— 免费档 403；仅付费。
  • /history 在云端改名为 /history_v2（脚本自动路由）。
  • /models/<folder> 在云端改名为 /experiment/models/<folder>（脚本自动路由）。
  • WebSocket 里的 clientId 目前被忽略——一个用户的所有连接收到同样的广播。在客户端按 prompt_id 过滤。
  • 上传接受 subfolder 但忽略——云端是扁平命名空间。
• 并发任务： 免费/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 数组）会提示你通过 "Workflow → Export (API)"（较新 UI）或 "Save (API Format)"（较旧 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 秒跳到 900 秒。用 --timeout 1800 显式覆盖。

8. 输出文件名里的路径穿越 —— 服务器给的文件名经过 safe_path_join，拒绝任何逃出 --output-dir 的东西。保留这层保护——带自定义保存节点的工作流可能产出任意路径。

9. 工作流 JSON 是任意代码 —— 自定义节点跑 Python，所以提交一个未知工作流的信任风险和 eval 一样。运行前检查来自不可信来源的工作流。

10. 自动随机种子 —— 在 --args 里传 seed: -1（或用 --randomize-seed 并省略 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 至少显示一个 checkpoint（本地），或 /api/experiment/models/checkpoints 返回模型（云端）
•  工作流 JSON 是 API 格式
•  check_deps.py 报告 is_ready: true（或云端免费档仅有 node_check_skipped）
•  用小工作流测试跑通；输出落到 --output-dir