| 无头 / 服务器 / CI / 智能体 | **路径 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
在 https://comfy.org/cloud 注册
在 https://platform.comfy.org/login 生成 API 密钥
设置密钥：
export COMFY_CLOUD_API_KEY="comfyui-xxxxxxxxxxxx"
运行工作流：
python3 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。免费套餐
无法通过 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（全平台——推荐智能体使用）
官方 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/Windows）。通过 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
安装后：验证
python3 scripts/health_check.py
# → comfy_cli on PATH? server reachable? checkpoints? smoke test?
python3 scripts/check_deps.py my_workflow.json
# → are this workflow's nodes/models/embeddings installed?
python3 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：
python3 scripts/run_workflow.py
--workflow workflows/sdxl_img2img.json
--input-image image=./photo.png
--args '{"prompt": "make it cyberpunk", "denoise": 0.6}'
该标志会上传 photo.png，然后将其服务器端文件名注入
schema 中名为 image 的参数。对于 inpainting，请同时传入：
python3 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 密钥：设置一次 $COMFY_CLOUD_API_KEY，脚本会自动识别
输出下载：/api/view 返回 302 重定向到签名 URL；脚本
会跟随重定向，并在从存储后端获取前剥离 X-API-Key
（不要将 API 密钥泄露给 S3/CloudFront）。
与本地 ComfyUI 的端点差异：
/api/object_info、/api/queue、/api/userdata — 免费套餐返回 403；
仅付费可用。
云端将 /history 重命名为 /history_v2（脚本会自动
路由）。
云端将 /models/ 重命名为 /experiment/models/
（脚本会自动路由）。
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 | python3 -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:
python3 scripts/fetch_logs.py --tail-queue --host https://cloud.comfy.org
注意事项
必须使用 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 工作区。
如果命令报错"no workspace found"，请使用
comfy --workspace /path/to/ComfyUI 或
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 相同。
运行前请检查来自不可信来源的工作流。
自动随机种子——在 --args 中传入 seed: -1（或使用
--randomize-seed 并省略 seed）即可让每次运行获得新种子。
实际使用的种子会记录到 stderr。
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
