---
title: "Comfyui"
sidebar_label: "Comfyui"
description: "使用 ComfyUI 生成图像、视频和音频——安装、启动、管理节点/模型、运行带参数注入的工作流"
---

{/* 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`](/user-guide/skills/optional/mlops/mlops-stable-diffusion) |

## 参考：完整 SKILL.md

:::info
以下是 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](https://github.com/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 生成

## 架构：两层

<!-- ascii-guard-ignore -->
```
┌─────────────────────────────────────────────────────┐
│ 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    │
└─────────────────────────────────────────────────────┘
```
<!-- ascii-guard-ignore-end -->

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

## 快速开始

### 检测环境

```bash
# 检查可用内容
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"

# 此机器能否在本地运行 ComfyUI？（GPU/VRAM/磁盘检查）
python3 scripts/hardware_check.py
```

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

### 一行健康检查

```bash
python3 scripts/health_check.py
# → JSON: comfy_cli 在 PATH 中？服务器可达？至少有一个 checkpoint？冒烟测试通过？
```

## 核心工作流

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

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

- ComfyUI Web UI → **Workflow → Export (API)**（新版 UI）或旧版"Save (API Format)"按钮（旧版 UI）
- 此 skill 的 `workflows/` 目录（可直接运行的示例）
- 社区下载（civitai、Reddit、Discord）——通常为编辑器格式，必须加载到 ComfyUI 后重新导出

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

### 第二步：查看可控内容

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

python3 scripts/extract_schema.py workflow_api.json
# → 完整 schema，包含参数、模型依赖、embedding 引用
```

### 第三步：带参数运行

```bash
# 本地（默认 http://127.0.0.1:8188）
python3 scripts/run_workflow.py \
  --workflow workflow_api.json \
  --args '{"prompt": "a beautiful sunset over mountains", "seed": -1, "steps": 30}' \
  --output-dir ./outputs

# 云端（一次性导出 API key；自动使用正确的 /api 路由）
export COMFY_CLOUD_API_KEY="comfyui-..."
python3 scripts/run_workflow.py \
  --workflow workflow_api.json \
  --args '{"prompt": "..."}' \
  --host https://cloud.comfy.org \
  --output-dir ./outputs

# 通过 WebSocket 实时查看进度（需要 `pip install websocket-client`）
python3 scripts/run_workflow.py \
  --workflow flux_dev.json \
  --args '{"prompt": "..."}' \
  --ws

# img2img / inpaint：传入 --input-image 自动上传并引用
python3 scripts/run_workflow.py \
  --workflow sdxl_img2img.json \
  --input-image image=./photo.png \
  --args '{"prompt": "make it watercolor", "denoise": 0.6}'

# 批量 / sweep：8 个随机种子，并行数量受限于云端套餐层级
python3 scripts/run_batch.py \
  --workflow sdxl.json \
  --args '{"prompt": "abstract"}' \
  --count 8 --randomize-seed --parallel 3 \
  --output-dir ./outputs/batch
```

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

### 第四步：呈现结果

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

```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 中选择。
- **不确定** → 运行硬件检查，由结果决定。

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

```bash
python3 scripts/hardware_check.py --json
# 可选：同时探测 `torch` 以获取实际 CUDA/MPS 信息：
python3 scripts/hardware_check.py --json --check-pytorch
```

| 结果 | 含义 | 操作 |
|------------|---------------------------------------------------------------|--------|
| `ok` | ≥8 GB VRAM（独立显卡）或 ≥32 GB 统一内存（Apple Silicon） | 本地安装——使用报告中的 `comfy_cli_flag` |
| `marginal` | SD1.5 可用；SDXL 较紧张；Flux/视频不太可能 | 轻量工作流可本地，否则选**路径 A（Cloud）** |
| `cloud` | 无可用 GPU、&lt;6 GB VRAM、&lt;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** |

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

```bash
bash scripts/comfyui_setup.sh
# 或带覆盖参数：
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：
   ```bash
   export COMFY_CLOUD_API_KEY="comfyui-xxxxxxxxxxxx"
   ```
4. 运行工作流：
   ```bash
   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
**并发任务：** 免费/标准版 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

```bash
# 推荐：
pipx install comfy-cli
# 或不安装直接使用 uvx：
uvx --from comfy-cli comfy --help
# 或（如果 pipx/uvx 不可用）：
pip install --user comfy-cli
```

非交互式禁用分析：
```bash
comfy --skip-prompt tracking disable
```

#### 安装 ComfyUI

```bash
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（较慢）
comfy --skip-prompt install --nvidia --fast-deps  # 基于 uv 的依赖解析
```

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

#### 启动 / 验证

```bash
comfy launch --background                       # 后台守护进程，端口 :8188
comfy launch -- --listen 0.0.0.0 --port 8190    # 局域网可访问的自定义端口
curl -s http://127.0.0.1:8188/system_stats      # 健康检查
```

---

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

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

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

```bash
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
```

---

### 安装后：下载模型

```bash
# SDXL（通用，约 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（更轻量，约 4 GB，适合 6 GB 显卡）
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（较小变体，约 12 GB）
comfy model download \
  --url "https://huggingface.co/Comfy-Org/flux1-dev/resolve/main/flux1-dev-fp8.safetensors" \
  --relative-path models/checkpoints

# CivitAI（先设置 token）：
comfy model download \
  --url "https://civitai.com/api/download/models/128713" \
  --relative-path models/checkpoints \
  --set-civitai-api-token "YOUR_TOKEN"
```

列出已安装：`comfy model list`。

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

```bash
comfy node install comfyui-impact-pack             # 常用工具包
comfy node install comfyui-animatediff-evolved     # 视频生成
comfy node install comfyui-controlnet-aux          # ControlNet 预处理器
comfy node install comfyui-essentials              # 常用辅助工具
comfy node update all
comfy node install-deps --workflow=workflow.json   # 安装工作流所需的全部内容
```

### 安装后：验证

```bash
python3 scripts/health_check.py
# → comfy_cli 在 PATH 中？服务器可达？有 checkpoint？冒烟测试？

python3 scripts/check_deps.py my_workflow.json
# → 此工作流的节点/模型/embedding 是否已安装？

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`：

```bash
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，同时传入：

```bash
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 手动上传：
```bash
curl -X POST "http://127.0.0.1:8188/upload/image" \
  -F "image=@photo.png" -F "type=input" -F "overwrite=true"
# 返回：{"name": "photo.png", "subfolder": "", "type": "input"}

# 云端等效：
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；脚本会跟随跳转并在从存储后端（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` 充分利用你的套餐层级。

## 队列与系统管理

```bash
# 本地
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}'    # 取消待处理任务
curl -X POST http://127.0.0.1:8188/interrupt                      # 取消运行中任务
curl -X POST http://127.0.0.1:8188/free \
  -H "Content-Type: application/json" \
  -d '{"unload_models": true, "free_memory": true}'

# 云端——相同路径加 /api/ 前缀，另外：
python3 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 workspace。如果命令报错"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` 会自动处理此问题。

## 验证清单

使用 `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` 中