comfy-cli run 快速上手从 UI 格式 JSON 自动转换到实时进度推送一条命令跑通 ComfyUI 工作流【免费下载链接】comfy-cliCLI for using ComfyUI项目地址: https://gitcode.com/gh_mirrors/co/comfy-cli如果你想在终端里执行 ComfyUI 工作流comfy-cli的comfy run就是为此而生的命令。comfy-cli 是 ComfyUI 官方出品的命令行工具可以完成 ComfyUI 的安装、启动、扩展节点管理和工作流执行。而comfy run则让你用一条命令把工作流提交到本地 ComfyUI 服务器或 Comfy Cloud 执行并实时推送每个节点的执行进度。本文面向新手带你完整走一遍安装 comfy-cli → 准备工作流 JSON → 自动转换 UI 格式 → 执行并观察实时进度 → 云端执行与结果下载最后附上常见报错的处理方法。一键安装 comfy-cli执行工作流前先安装 comfy-cli需要 Python 3.10推荐在虚拟环境中安装pip install comfy-cli comfy setupcomfy setup是一个交互式向导一次性帮你完成本地/云端路由、登录认证和 Agent 技能安装在 CI 或脚本中可加-y跳过交互。如果本机还没有 ComfyUI接着执行comfy install # 一键安装 ComfyUI 和 ComfyUI-Manager comfy launch # 启动 ComfyUI默认地址 127.0.0.1:8188 如果 ComfyUI 运行在非默认地址可以用export COMFY_LOCAL_URLhttp://127.0.0.1:8189指向它comfy run、comfy jobs、comfy download等命令都会自动识别。准备工作流 JSONUI 格式和 API 格式的区别ComfyUI 能导出两种 JSON这是新手最容易卡住的点格式来源结构特征能否直接执行UI 格式菜单 File → Save含nodes、links、坐标等界面信息❌ 不能API 格式菜单 File → Export (API)每个节点带class_type和inputs✅ 能好消息是comfy run不需要你手动转换。它会先探测文件结构——只要发现顶层同时存在nodes和links两个数组就判定为 UI 格式工作流随后自动调用内置转换器把它转成 API 格式再提交。相关逻辑分别在 comfy_cli/command/run/loader.py格式探测和 comfy_cli/workflow_to_api.pyUI 转 API 实现中。也就是说你从 ComfyUI 网页端直接 Save 出来的工作流文件拿过来就能跑。comfy run 核心用法一条命令执行工作流最基本的执行命令comfy run --workflow ./workflow.json执行流程分四步加载并探测—— 读取 JSON判断是 UI 格式还是 API 格式UI 格式自动转换预检preflight—— 从服务器拉取object_info校验工作流里每个节点的class_type是否真实存在缺节点会提前报错并列出具体节点而不是执行到一半才失败提交—— 通过 HTTP POST 到/prompt端点返回唯一的prompt_id实时推送—— 建立 WebSocket 连接边执行边输出进度。常用参数速查表参数作用--workflow file指定工作流 JSON 文件--where cloud提交到 Comfy Cloud 执行无需本地 GPU--wait阻塞直到任务完成异步提交则立即返回--json输出结构化 JSON 信封方便脚本和 AI Agent 解析--prompt 文本不传--workflow时用内置默认文生图工作流--set keyvalue覆盖工作流中某个节点输入如--set checkpointxxx.ckpt执行完成会输出每个节点的执行状态和产出图片信息加--json后同样的信息会以统一的结构化信封输出信封 schema 见 comfy_cli/schemas/run.json非常适合接进自动化脚本。实时进度推送每个节点的执行状态一目了然comfy run在执行过程中通过 WebSocket 监听服务器事件实时映射为一组结构化进度事件见 comfy_cli/command/run/execution.pyexecuting—— 节点开始执行显示节点标题和类型execution_cached—— 节点命中缓存秒过progress—— 采样类节点的completed/total进度如 15/20executed—— 节点完成及其产出output—— 每个输出文件单独列出方便直接取用execution_error—— 报错事件附带出错节点和错误详情这些事件与comfy jobs watch输出的是同一套方言所以本地执行和云端任务监控的体验完全一致。云端执行没有本地 GPU 也能跑如果你没有本地 GPU用--where cloud把任意工作流路由到 Comfy Cloud按 GPU 秒计费需要 Comfy 账号和积分comfy cloud login # 浏览器 OAuth 登录只需一次 comfy run --workflow ./workflow.json --where cloud comfy jobs wait prompt_id --where cloud # 阻塞等待任务完成 comfy download prompt_id --where cloud -o ./outputs云端执行是异步提交comfy run提交后打印prompt_id并立即返回之后用comfy jobs status查状态、comfy jobs watch看实时进度、comfy download下载结果。也可以用管道把提交和下载串起来comfy run --workflow w.json --where cloud | comfy download --where cloud两个实用技巧执行含合作伙伴节点如 Kling、Flux 等会消耗积分的模型的工作流时comfy run会先弹出消费确认闸门明确列出将消耗积分的节点确认后才提交防止误扣费想让所有命令默认走云端执行comfy set-default --where cloud之后可以省略--where参数。常见报错与排查现象原因与解决workflow_emptyJSON 是空对象检查工作流是否导出完整节点 class_type 不存在服务器缺对应自定义节点用comfy node install 节点ID安装后重试cloud_unauthorized云端会话过期重新执行comfy cloud login积分不足用comfy cloud status查看余额充值后再提交找不到目标 ComfyUI用comfy which查看当前指向的 workspace 路径⚠️ 注意comfy run --prompt ...不传工作流走的是内置默认文生图流程它需要 SD1.5 检查点v1-5-pruned-emaonly.ckptcomfy-cli 不会替你下载需自行放入models/checkpoints目录或用--set checkpoint你的模型名指定已有模型。小结comfy run把导出工作流 → 转格式 → 提交 → 盯进度 → 下载这条链路压缩成了一条命令UI 格式 JSON 自动转换、节点级实时进度推送、本地/云端一键切换、结构化 JSON 输出适配 Agent 和脚本。配合 comfy_cli/command/run/ 模块下 loader、preflight、execution、watcher 四个子模块每一步都有明确职责出问题时也能快速定位。现在打开终端执行你的第一条comfy run --workflow ./workflow.json吧【免费下载链接】comfy-cliCLI for using ComfyUI项目地址: https://gitcode.com/gh_mirrors/co/comfy-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/8/25 17:48:28 · 阅读 1.2k comfy-cli run 快速上手：从 UI 格式 JSON 自动转换到实时进度推送，一条命令跑通 ComfyUI 工作流
comfy-cli run 快速上手从 UI 格式 JSON 自动转换到实时进度推送一条命令跑通 ComfyUI 工作流【免费下载链接】comfy-cliCLI for using ComfyUI项目地址: https://gitcode.com/gh_mirrors/co/comfy-cli如果你想在终端里执行 ComfyUI 工作流comfy-cli的comfy run就是为此而生的命令。comfy-cli 是 ComfyUI 官方出品的命令行工具可以完成 ComfyUI 的安装、启动、扩展节点管理和工作流执行。而comfy run则让你用一条命令把工作流提交到本地 ComfyUI 服务器或 Comfy Cloud 执行并实时推送每个节点的执行进度。本文面向新手带你完整走一遍安装 comfy-cli → 准备工作流 JSON → 自动转换 UI 格式 → 执行并观察实时进度 → 云端执行与结果下载最后附上常见报错的处理方法。一键安装 comfy-cli执行工作流前先安装 comfy-cli需要 Python 3.10推荐在虚拟环境中安装pip install comfy-cli comfy setupcomfy setup是一个交互式向导一次性帮你完成本地/云端路由、登录认证和 Agent 技能安装在 CI 或脚本中可加-y跳过交互。如果本机还没有 ComfyUI接着执行comfy install # 一键安装 ComfyUI 和 ComfyUI-Manager comfy launch # 启动 ComfyUI默认地址 127.0.0.1:8188 如果 ComfyUI 运行在非默认地址可以用export COMFY_LOCAL_URLhttp://127.0.0.1:8189指向它comfy run、comfy jobs、comfy download等命令都会自动识别。准备工作流 JSONUI 格式和 API 格式的区别ComfyUI 能导出两种 JSON这是新手最容易卡住的点格式来源结构特征能否直接执行UI 格式菜单 File → Save含nodes、links、坐标等界面信息❌ 不能API 格式菜单 File → Export (API)每个节点带class_type和inputs✅ 能好消息是comfy run不需要你手动转换。它会先探测文件结构——只要发现顶层同时存在nodes和links两个数组就判定为 UI 格式工作流随后自动调用内置转换器把它转成 API 格式再提交。相关逻辑分别在 comfy_cli/command/run/loader.py格式探测和 comfy_cli/workflow_to_api.pyUI 转 API 实现中。也就是说你从 ComfyUI 网页端直接 Save 出来的工作流文件拿过来就能跑。comfy run 核心用法一条命令执行工作流最基本的执行命令comfy run --workflow ./workflow.json执行流程分四步加载并探测—— 读取 JSON判断是 UI 格式还是 API 格式UI 格式自动转换预检preflight—— 从服务器拉取object_info校验工作流里每个节点的class_type是否真实存在缺节点会提前报错并列出具体节点而不是执行到一半才失败提交—— 通过 HTTP POST 到/prompt端点返回唯一的prompt_id实时推送—— 建立 WebSocket 连接边执行边输出进度。常用参数速查表参数作用--workflow file指定工作流 JSON 文件--where cloud提交到 Comfy Cloud 执行无需本地 GPU--wait阻塞直到任务完成异步提交则立即返回--json输出结构化 JSON 信封方便脚本和 AI Agent 解析--prompt 文本不传--workflow时用内置默认文生图工作流--set keyvalue覆盖工作流中某个节点输入如--set checkpointxxx.ckpt执行完成会输出每个节点的执行状态和产出图片信息加--json后同样的信息会以统一的结构化信封输出信封 schema 见 comfy_cli/schemas/run.json非常适合接进自动化脚本。实时进度推送每个节点的执行状态一目了然comfy run在执行过程中通过 WebSocket 监听服务器事件实时映射为一组结构化进度事件见 comfy_cli/command/run/execution.pyexecuting—— 节点开始执行显示节点标题和类型execution_cached—— 节点命中缓存秒过progress—— 采样类节点的completed/total进度如 15/20executed—— 节点完成及其产出output—— 每个输出文件单独列出方便直接取用execution_error—— 报错事件附带出错节点和错误详情这些事件与comfy jobs watch输出的是同一套方言所以本地执行和云端任务监控的体验完全一致。云端执行没有本地 GPU 也能跑如果你没有本地 GPU用--where cloud把任意工作流路由到 Comfy Cloud按 GPU 秒计费需要 Comfy 账号和积分comfy cloud login # 浏览器 OAuth 登录只需一次 comfy run --workflow ./workflow.json --where cloud comfy jobs wait prompt_id --where cloud # 阻塞等待任务完成 comfy download prompt_id --where cloud -o ./outputs云端执行是异步提交comfy run提交后打印prompt_id并立即返回之后用comfy jobs status查状态、comfy jobs watch看实时进度、comfy download下载结果。也可以用管道把提交和下载串起来comfy run --workflow w.json --where cloud | comfy download --where cloud两个实用技巧执行含合作伙伴节点如 Kling、Flux 等会消耗积分的模型的工作流时comfy run会先弹出消费确认闸门明确列出将消耗积分的节点确认后才提交防止误扣费想让所有命令默认走云端执行comfy set-default --where cloud之后可以省略--where参数。常见报错与排查现象原因与解决workflow_emptyJSON 是空对象检查工作流是否导出完整节点 class_type 不存在服务器缺对应自定义节点用comfy node install 节点ID安装后重试cloud_unauthorized云端会话过期重新执行comfy cloud login积分不足用comfy cloud status查看余额充值后再提交找不到目标 ComfyUI用comfy which查看当前指向的 workspace 路径⚠️ 注意comfy run --prompt ...不传工作流走的是内置默认文生图流程它需要 SD1.5 检查点v1-5-pruned-emaonly.ckptcomfy-cli 不会替你下载需自行放入models/checkpoints目录或用--set checkpoint你的模型名指定已有模型。小结comfy run把导出工作流 → 转格式 → 提交 → 盯进度 → 下载这条链路压缩成了一条命令UI 格式 JSON 自动转换、节点级实时进度推送、本地/云端一键切换、结构化 JSON 输出适配 Agent 和脚本。配合 comfy_cli/command/run/ 模块下 loader、preflight、execution、watcher 四个子模块每一步都有明确职责出问题时也能快速定位。现在打开终端执行你的第一条comfy run --workflow ./workflow.json吧【免费下载链接】comfy-cliCLI for using ComfyUI项目地址: https://gitcode.com/gh_mirrors/co/comfy-cli创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考