入门 - 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

获取 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

安装 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 环境变量硬性选择退出。

​概述

​安装 CLI

​快速设置（推荐）

​安装 ComfyUI (本地)

​运行 ComfyUI（本地）

​Comfy Cloud

​使用合作节点生成

​前置条件

​首次生成

​常用模型

​探索模型

​使用参考图像进行编辑

​视频生成（异步任务）

​用于脚本的 JSON 输出

​运行工作流（comfy run）

​从模板开始

​原地编辑工作流

​发现节点和模型

​上传和下载文件

​管理自定义节点

​管理模型（本地）

​脚本和代理的JSON输出

​代理技能

​贡献指南

​分析

概述

安装 CLI

快速设置（推荐）

安装 ComfyUI (本地)

运行 ComfyUI（本地）

Comfy Cloud

使用合作节点生成

前置条件

首次生成

常用模型

探索模型

使用参考图像进行编辑

视频生成（异步任务）

用于脚本的 JSON 输出

运行工作流（`comfy run`）

从模板开始

原地编辑工作流

发现节点和模型

上传和下载文件

管理自定义节点

管理模型（本地）

脚本和代理的JSON输出

代理技能

贡献指南

分析