入门 - ComfyUI

概述

comfy-cli 是一个命令行工具，可简化 Comfy 的安装与管理，并通过脚本化的单条指令在本地或云端访问整个 ComfyUI 生态系统。它主要提供三种功能：

管理本地 ComfyUI 安装 —— 安装、启动、更新、快照和二分查找 ComfyUI 及自定义节点。
访问托管合作节点 —— 通过单条指令从 Seedance、Nano Banana (Gemini)、Grok、Flux、Ideogram、DALL·E、Recraft、Stability、Kling、Luma、Runway、Pika、Vidu、Hailuo、Moonvalley 等提供商生成图像、视频、音频和 3D 内容。
在 Comfy Cloud 上运行完整工作流 —— 提交工作流图、浏览精心策划的模板图库、槽位编辑工作流，并监控任务直至完成，无需本地 GPU。

两个环境，一个 CLI。 每条指令会自动检测运行位置。如果您已登录 Comfy Cloud，指令将路由到云端；否则在本地服务器上执行。每次调用可通过 --where local|cloud 覆盖，或使用 COMFY_WHERE 环境变量，或用 comfy set-default --where cloud 持久化设置。

安装 CLI

pip install comfy-cli

brew tap Comfy-Org/comfy-cli
brew install comfy-org/comfy-cli/comfy-cli

获取 shell 自动补全提示：

comfy --install-completion

快速设置（推荐）

最近版本的新功能：一个交互式向导，可在一步中处理路由、认证和代理技能。

comfy setup

它将引导您选择路由目标（本地或云端），通过浏览器登录（OAuth），选择项目目录，并可选择安装代理技能。这是推荐路径。它会自动打开浏览器登录页面，无需复制密钥。

comfy setup --where cloud

非交互模式（仅限CI）。 浏览器OAuth需要交互式会话。对于CI、开发容器以及无法使用浏览器的脚本化安装，请改用API密钥：

comfy setup --where cloud --api-key comfyui-... --non-interactive

标志	用途
`--where local\|cloud`	路由目标；跳过提示
`--project-dir`	工作流、输入和输出的目录
`--api-key`	（可选）用于无头/CI环境的Comfy Cloud API密钥；隐式指定`--where cloud`
`-y, --non-interactive`	无提示。所有配置均由标志驱动
`--skip-skills`	不安装代理技能
`--skip-verify`	跳过连通性检查

安装 ComfyUI (本地)

使用任意高于 3.9 的 Python 版本创建一个虚拟环境。

conda create -n comfy-env python=3.11
conda activate comfy-env

python3 -m venv comfy-env
source comfy-env/bin/activate

安装 ComfyUI

comfy install

您仍然需要根据您的 GPU 安装 CUDA 或 ROCm。

运行 ComfyUI（本地）

comfy launch

在后台运行，稍后停止：

comfy launch --background
comfy stop

检查当前选择的工作区以及已安装的内容：

comfy which
comfy env

Comfy Cloud

在 Comfy 托管的 GPU 上运行工作流和合作节点，无需本地安装。

comfy cloud login          # 浏览器 OAuth + PKCE
comfy cloud whoami         # 显示登录状态、认证方法、基础 URL
comfy cloud logout         # 清除本地会话

登录后，指令将自动路由至云端。**浏览器 OAuth 是推荐的路径。**无需管理密钥，CLI 会自动为您刷新令牌。要在登录前指向自定义环境（例如 PR 预览），请执行：

comfy cloud set-base-url https://my-preview.comfy.org

**API 密钥是可选的。**仅当在无头环境或 CI 中使用，且无法通过浏览器登录时，才需要 API 密钥。它作为备用方案，并非默认方式：

export COMFY_API_KEY=comfyui-...   # 或在每次调用时传递 --api-key

**会话生命周期。**Cloud 会话令牌有效期较短（约1小时）。CLI 会根据需要自动刷新。如果某个指令报告 cloud_unauthorized，请重新运行 comfy cloud login。

使用合作节点生成

comfy generate 处于测试阶段。 标志名称、模型别名和输出格式可能会更改。底层的合作伙伴端点保持稳定。请在 comfy-cli GitHub 仓库提交反馈。

从终端或脚本调用 Comfy 的合作节点的最快方式。它访问与 ComfyUI 工作流相同的托管端点，但作为单个 CLI 调用。非常适合批处理任务、快速实验和自动化场景，无需完整的 ComfyUI 画面图。

前置条件

通过 comfy cloud login（浏览器 OAuth）获得活跃的 Comfy Cloud 会话，或对于无头或 CI 使用，需要一个 Comfy API 密钥（--api-key / COMFY_API_KEY）
您账户上的积分
可选： 浏览合作节点与按次调用定价

首次生成

comfy generate flux-pro \
    --prompt "a cat on the moon, cinematic lighting" \
    --width 1024 --height 1024 \
    --download cat.png

CLI 会上传本地文件，提交任务，轮询完成状态，并保存结果。

先了解模型的实际参数。不同模型的标志名不同（例如 flux-ultra 使用 --width/--height；seedance 使用 --ratio/--resolution/--duration）。在编写脚本前务必检查：

comfy generate schema flux-ultra

常用模型

Nano Banana (Google Gemini)：文生图与编辑：

comfy generate nano-banana \
    --prompt "a watercolor of a sleeping fox" \
    --download fox.png

# Image editing:
comfy generate nano-banana \
    --prompt "add a top hat" \
    --image ./cat.png \
    --download edited.png

# Specify a model variant:
comfy generate nano-banana \
    --prompt "neon city skyline" \
    --model gemini-3-pro-image-preview \
    --download city.png

Flux 1.1 Pro Ultra：高分辨率文生图：

comfy generate flux-ultra \
    --prompt "a purple Victorian house in San Francisco, golden hour" \
    --width 896 --height 1152 --seed 11 \
    --download house.png

Seedance（字节跳动）：文生视频和图生视频，最高支持1080p/12秒：

# Text-to-video:
comfy generate seedance \
    --prompt "a hummingbird hovering over a flower" \
    --resolution 1080p --duration 5 \
    --download hummingbird.mp4

# Image-to-video (animate a local image, auto-uploaded):
comfy generate seedance \
    --model seedance-1-0-pro-250528 \
    --image ./painting.png \
    --ratio 3:4 --resolution 1080p --duration 5 \
    --prompt "the painting gently comes alive, a soft breeze stirs the trees" \
    --download animated.mp4

Grok (xAI)：图像与视频：

comfy generate grok --prompt "a cyberpunk street market at night" --download street.png
comfy generate grok-edit --prompt "swap the umbrella for a parasol" --image ./photo.jpg --download out.png
comfy generate grok-video --prompt "a paper plane gliding through a cathedral" --download flight.mp4

探索模型

comfy generate list                            # 全部模型
comfy generate list --category text-to-video   # 按类别筛选：文生视频
comfy generate list --partner kling            # 按合作伙伴筛选
comfy generate schema flux-kontext             # 查看模型参数

使用参考图像进行编辑

传递本地文件路径。CLI 通过 Comfy 的存储端点上传或按需进行 base64 编码：

comfy generate nano-banana \
    --prompt "add a top hat" \
    --image ./cat.png \
    --download edited.png

comfy generate flux-kontext \
    --prompt "add a top hat and a monocle" \
    --input_image ./photo.jpg \
    --download out.png

comfy generate ideogram-edit \
    --image cat.png --mask mask.png \
    --prompt "add sunglasses" \
    --rendering_speed TURBO \
    --download edited.png

要上传一次并在多次调用中重复使用：

comfy generate upload ./photo.jpg     # 打印一个已签名的 URL

上传的参考资产将在24小时后自动删除。它们存储在Comfy管理的GCS中，并使用带签名的URL。对于长期运行的pipeline，请在每次任务之前重新上传。详情请参阅reference。

视频生成（异步任务）

视频任务是异步的。CLI 默认会阻塞并轮询：

comfy generate seedance \
    --prompt "a hummingbird hovering over a flower" \
    --resolution 1080p --duration 5 \
    --download hummingbird.mp4

comfy generate kling \
    --prompt "a paper boat drifting on a river at dusk" \
    --duration 5 \
    --download boat.mp4

使用 --async 立即返回，稍后恢复：

comfy generate luma --prompt "neon koi swimming through clouds" --aspect_ratio 16:9 --async
# prints a job id; resume with:
comfy generate resume luma <job_id> --download out.mp4

用于脚本的 JSON 输出

输出原始 API 响应以集成到管道中：

comfy generate dalle --prompt "a watercolor whale" --json | jq '.data[0].url'

有关命令、标志和模型别名的完整列表，请参阅参考。

运行工作流（`comfy run`）

除了单个合作伙伴调用之外，comfy run 会提交一个完整的 ComfyUI 工作流图。它接受 API 格式和导出的 UI 格式 JSON（UI 工作流会在客户端转换为 API 格式），并像其他所有指令一样路由到本地或云端。它默认异步运行。它会在毫秒内返回一个 prompt_id，同时后台观察者会跟踪进度。使用 --wait 可以改为阻塞模式。

# 提交，立即返回 prompt_id
RES=$(comfy --json run --workflow my_workflow.json)
PROMPT_ID=$(echo "$RES" | jq -r .data.prompt_id)

# 等待直到终端态，然后收集输出
comfy --json jobs watch "$PROMPT_ID" | comfy download

更喜欢单次阻塞调用？使用 --wait：

comfy run --workflow my_workflow.json --wait | comfy download

跟踪和管理任务：

comfy jobs ls                 # 本地异步提交 + 服务器队列/历史
comfy jobs status <prompt_id> # 单个任务
comfy jobs wait <id1> <id2>   # 阻塞直到所有任务达到终端态
comfy jobs cancel <prompt_id> # 幂等操作

提交之前先验证。在消耗云端算力前，捕捉未知节点、缺失模型和错误连接：

comfy validate --workflow my_workflow.json

从模板开始

精心策划的 Comfy-Org/workflow_templates 图库是快速获取特定任务已知良好工作流的最快方式。无需从头构建。

comfy templates ls --type image --tag "Text to Image"   # browse
comfy templates show <name>                              # full metadata
comfy templates fetch <name> --out my.json               # pull the workflow JSON

下载的 JSON 是前端格式。comfy run --where cloud 在提交时自动将其转换为 API 格式。

原地编辑工作流

comfy workflow 公开了任何前端格式工作流中可被 agent 调整的槽位，并允许您覆盖它们。无需手动处理 JSON。

comfy workflow slots my.json                 # 列出可寻址的槽位
comfy workflow set-slot my.json 6.text="a fox in the snow"
comfy workflow vary my.json \
    --slot positive.text='["a cat","a dog","a fox"]' \
    --out-dir ./variants                     # 生成 N 个变体

Comfy Cloud 上已保存的工作流：

comfy workflow list                          # 您已保存的工作流
comfy workflow get <id> --out my.json
comfy workflow save my.json --name "My Flow"
comfy workflow delete <id>

对于复杂的多步骤管道，可将小型可复用片段组合成一个画面：

comfy workflow compose blueprints/my_pipeline.yaml -o workflows/my_pipeline.json
comfy workflow decompose my.json             # 反向操作：将工作流投影为片段

发现节点和模型

对解析的后端上的所有内容进行内省。 节点：

comfy nodes search "checkpoint"              # fuzzy search
comfy nodes show KSampler                    # full schema: inputs, outputs, defaults
comfy nodes ls --produces IMAGE --limit 10   # filter by output type
comfy nodes ls --api-only                    # partner-API nodes only

模型：

comfy models list-folders                    # every model folder
comfy models search --text "wan2.2" --type lora
comfy models show wan2.2_vae.safetensors     # full metadata

上传和下载文件

comfy upload photo.png video.mp4             # → 服务器输入目录
comfy download <prompt_id>                   # → ./输出/

惯用管道：

comfy run --workflow flux.json --wait | comfy download

comfy download 会从管道标准输入中自动读取 prompt_id 和输出 URLs，无需手动提取键值，也无需 jq。

管理自定义节点

comfy node install <NODE_NAME>

该工具使用 cm-cli 来安装自定义节点。详情请参阅 ComfyUI 管理器 cm-cli 文档。

管理模型（本地）

轻松下载模型：

comfy model download --url <url> --relative-path models/checkpoints

脚本和代理的JSON输出

每条指令都接受 --json 并以相同的信封形状输出，使CLI完全可脚本化且对代理友好：

{
  "ok": true,
  "command": "...",
  "version": "1.11.1",
  "where": "local | cloud | null",
  "data": { },
  "error": null
}

当存在 error 时，读取 hint 并按提示操作：

comfy --json run --workflow my.json | jq '.error.hint'

代理面向的接口完全自描述。转储整个指令树、输出模式和错误代码：

comfy --json discover

代理技能

将捆绑的Comfy代理技能安装到Claude Code、Cursor以及任何支持AGENTS.md的工具中，让你的编码代理可以直接驱动CLI：

comfy skills install
comfy skills list      # comfy, comfy-fragments, comfy-debug, comfy-relay, comfy-director
comfy skills status    # 查看各工具中已安装的技能

这些是通过 comfy skills install 安装的捆绑版CLI技能。它们与 Comfy Skills 仓库是分开的，后者托管了 comfy-cloud Claude Code 插件，用于 Comfy Cloud MCP。

贡献指南

欢迎贡献。您可以在 comfy-cli GitHub 仓库中创建 Issue 或提交 Pull Request。更多详情请参阅开发指南。

分析

使用跟踪有助于改进CLI。可通过以下命令禁用：

comfy tracking disable

重新启用跟踪：

comfy tracking enable

你也可以通过 DO_NOT_TRACK 或 COMFY_NO_TELEMETRY 环境变量硬性选择退出。

ComfyUI APIs

CLI

开发自定义节点

注册表(Registry)

规范

入门

概述

安装 CLI

快速设置（推荐）

安装 ComfyUI (本地)

运行 ComfyUI（本地）

Comfy Cloud

使用合作节点生成

前置条件

首次生成

常用模型

探索模型

使用参考图像进行编辑

视频生成（异步任务）

用于脚本的 JSON 输出

运行工作流（`comfy run`）

从模板开始

原地编辑工作流

发现节点和模型

上传和下载文件

管理自定义节点

管理模型（本地）

脚本和代理的JSON输出

代理技能

贡献指南

分析

​概述

​安装 CLI

​快速设置（推荐）

​安装 ComfyUI (本地)

​运行 ComfyUI（本地）

​Comfy Cloud

​使用合作节点生成

​前置条件

​首次生成

​常用模型

​探索模型

​使用参考图像进行编辑

​视频生成（异步任务）

​用于脚本的 JSON 输出

​运行工作流（comfy run）

​从模板开始

​原地编辑工作流

​发现节点和模型

​上传和下载文件

​管理自定义节点

​管理模型（本地）

​脚本和代理的JSON输出

​代理技能

​贡献指南

​分析

概述

安装 CLI

快速设置（推荐）

安装 ComfyUI (本地)

运行 ComfyUI（本地）

Comfy Cloud

使用合作节点生成

前置条件

首次生成

常用模型

探索模型

使用参考图像进行编辑

视频生成（异步任务）

用于脚本的 JSON 输出

运行工作流（`comfy run`）

从模板开始

原地编辑工作流

发现节点和模型

上传和下载文件

管理自定义节点

管理模型（本地）

脚本和代理的JSON输出

代理技能

贡献指南

分析