ComfyClaw：用Python代码自动化操控ComfyUI工作流

1. 项目概述：当ComfyUI遇上“机械爪”

如果你和我一样，是个喜欢在ComfyUI里“折腾”各种工作流的玩家，那你肯定遇到过这样的场景：一个精心设计的流程，节点密密麻麻，每次想换个模型、改个参数，都得在画布上点来点去，拖来拖去。尤其是当你想批量测试不同模型组合，或者在不同工作流之间复用某个复杂节点组时，手动操作不仅繁琐，还容易出错。这时候，一个能自动“抓取”并“操控”这些节点的“机械爪”，就显得格外诱人。

ComfyClaw就是这样一个项目。它不是一个独立的图形界面应用，而是一个为ComfyUI设计的Python库和工具集。你可以把它想象成一个给ComfyUI装上的“自动化机械臂”。它的核心能力，是让你能够用Python代码的方式，去程序化地创建、连接、修改ComfyUI的工作流，并与之交互。这意味着，你可以将工作流的构建从手动拖拽的GUI操作，转变为可编程、可复用、可集成的脚本逻辑。

这解决了什么痛点？简单来说，它把工作流从“艺术品”变成了“可批量生产的工业品”。对于研究者，可以轻松编写脚本进行大规模的参数网格搜索；对于开发者，可以将其集成到自己的应用后端，动态生成工作流；对于高级用户，可以构建自己的“配方库”，一键生成复杂效果。ComfyClaw的目标，就是成为连接ComfyUI强大图形化能力与程序化自动化需求之间的那座桥梁。

2. 核心设计思路：以代码驱动节点图

要理解ComfyClaw，首先要理解ComfyUI工作流的本质。在ComfyUI中，一个工作流（Workflow）本质上是一个有向无环图（DAG）。每个节点（Node）是图中的一个顶点，节点之间的连接（Links）是图的边，数据（如图片、潜变量、条件等）沿着边流动。

手动操作时，我们在画布上“绘制”这个图。而ComfyClaw的思路是：用数据结构在内存中构建这个图，然后通过ComfyUI的API将其“注入”到运行中的ComfyUI服务里，或者直接生成可加载的JSON工作流文件。

2.1 抽象层设计：节点即对象，连接即赋值

ComfyClaw最巧妙的设计在于它的抽象层。它没有尝试去模拟鼠标点击和拖拽，而是将ComfyUI的节点类型（如KSampler,CLIPTextEncode,VAEDecode）映射为Python类。每个节点实例化后，其输入端口（input sockets）和输出端口（output sockets）就成为了这个对象的属性。

连接两个节点，在代码层面就变成了简单的属性赋值。例如，你想把CLIPTextEncode节点的输出，连接到KSampler节点的positive输入，代码可能看起来像这样：

ksampler.positive = clip_encode.output[0] # output[0] 通常指第一个输出端口

这种设计非常符合程序员的直觉。它隐藏了底层JSON结构中复杂的节点ID（id）和链接索引（link），让开发者可以更关注逻辑本身。

2.2 两种核心工作模式

根据我的使用经验，ComfyClaw主要支持两种与ComfyUI交互的模式：

模式一：API动态注入模式这是最强大、最交互式的模式。在此模式下，ComfyClaw会与一个正在运行的ComfyUI服务器（通过--listen参数启动）通信。你的Python脚本在内存中构建好节点图后，可以通过WebSocket或HTTP API，将整个图“推送”到ComfyUI服务端。ComfyUI会立即在界面上渲染出这些节点，并准备好执行。你还可以通过API触发执行、查询队列状态、获取生成结果。这非常适合构建交互式应用或实时工作流编排系统。

模式二：JSON文件生成模式这种模式更偏向于“离线”工作。ComfyClaw在内存中构建好节点图后，将其序列化为ComfyUI标准的工作流JSON文件。你可以保存这个文件，然后在任何ComfyUI图形界面中手动加载、查看和微调。这对于创建可分享、可版本管理的工作流“模板”非常有用。你可以用代码生成成百上千个变体工作流，然后逐个加载测试。

注意：这两种模式并非互斥。一个成熟的自动化流程可能是混合的：先用代码生成一批基础工作流JSON作为模板，再在运行时通过API模式动态调整参数并执行。

2.3 类型与数据流安全

ComfyUI的节点连接是有类型约束的，比如LATENT类型输出不能直接连到IMAGE类型输入。ComfyClaw的一个高级特性是会在代码层面尝试进行类型检查。虽然由于Python的动态特性，这无法做到编译时百分百安全，但库内部会维护节点端口的类型信息，并在连接时给出警告或错误提示，这能提前避免许多运行时错误。

3. 从零开始：环境搭建与基础用法

理论说得再多，不如上手一试。下面我将带你从零开始，配置环境并编写第一个ComfyClaw脚本。

3.1 环境准备

假设你已经有一个正常运行的ComfyUI环境。如果没有，请先按照官方指南安装。

1. 安装ComfyClaw： 最直接的方式是通过pip从GitHub安装。打开你的终端（在ComfyUI所在目录或独立的Python虚拟环境）：

   pip install git+https://github.com/BuffMcBigHuge/ComfyClaw.git

   这将会安装ComfyClaw及其依赖。

2. 启动ComfyUI API服务： 要让ComfyClaw以API模式工作，必须让ComfyUI以允许远程API访问的方式启动。进入你的ComfyUI目录，使用如下命令：

   python main.py --listen 0.0.0.0 --port 8188

   --listen 0.0.0.0允许所有网络接口的连接（如果只在本地使用，可以用127.0.0.1）。--port 8188是默认API端口。启动后，你应该能在http://localhost:8188看到ComfyUI的Web界面。

3.2 第一个脚本：生成一张简单的图片

让我们创建一个最简单的脚本，用ComfyClaw构建一个文生图流程，并让ComfyUI执行它。

创建一个名为first_claw.py的文件，内容如下：

import asyncio from comfyclaw import ComfyClaw, Node async def main(): # 1. 连接到运行中的ComfyUI服务器 claw = ComfyClaw(server_address="127.0.0.1", port=8188) # 2. 开始构建工作流 with claw.workflow() as wf: # 3. 创建节点实例 # CheckpointLoaderSimple: 加载模型 checkpoint = wf.add_node("CheckpointLoaderSimple", name="加载器") checkpoint.ckpt_name = "v1-5-pruned-emaonly.safetensors" # 你的模型文件名 # CLIPTextEncode: 编码正向提示词 clip_encode_pos = wf.add_node("CLIPTextEncode", name="正向提示词") clip_encode_pos.text = "masterpiece, best quality, a beautiful sunset over mountains" clip_encode_pos.clip = checkpoint.output[1] # 连接加载器输出的CLIP模型 # CLIPTextEncode: 编码负向提示词 clip_encode_neg = wf.add_node("CLIPTextEncode", name="负向提示词") clip_encode_neg.text = "worst quality, low quality, blurry" clip_encode_neg.clip = checkpoint.output[1] # EmptyLatentImage: 创建初始潜变量 latent = wf.add_node("EmptyLatentImage", name="潜变量") latent.width = 512 latent.height = 512 latent.batch_size = 1 # KSampler: 采样器 sampler = wf.add_node("KSampler", name="采样") sampler.seed = 42 sampler.steps = 20 sampler.cfg = 7.5 sampler.sampler_name = "euler" sampler.scheduler = "normal" sampler.denoise = 1.0 sampler.model = checkpoint.output[0] # 连接加载器输出的UNet模型 sampler.positive = clip_encode_pos.output[0] sampler.negative = clip_encode_neg.output[0] sampler.latent_image = latent.output[0] # VAEDecode: 解码潜变量为图片 vae_decode = wf.add_node("VAEDecode", name="解码") vae_decode.vae = checkpoint.output[2] # 连接加载器输出的VAE模型 vae_decode.samples = sampler.output[0] # SaveImage: 保存图片 save_image = wf.add_node("SaveImage", name="保存") save_image.filename_prefix = "comfyclaw_output" save_image.images = vae_decode.output[0] # 4. 将工作流发送到ComfyUI服务器并执行 print("正在将工作流发送到ComfyUI...") prompt_id = await claw.queue_prompt(wf) print(f"任务已加入队列，ID: {prompt_id}") # 5. 轮询并等待结果 print("等待生成完成...") images = await claw.wait_for_images(prompt_id) # 6. 保存结果到本地 for i, (image_data, filename) in enumerate(images): with open(f"output_{i}.png", "wb") as f: f.write(image_data) print(f"图片已保存: output_{i}.png") print("所有任务完成！") if __name__ == "__main__": asyncio.run(main())

代码解读与实操要点：

1. 连接与工作流上下文：ComfyClaw对象是主入口。claw.workflow()返回一个上下文管理器，在这个with块内创建的所有节点会自动归属于同一个工作流。
2. 节点创建与连接：wf.add_node(“节点类型”, name=”可选别名”)是创建节点的核心方法。连接通过给节点的输入属性赋值完成，值可以是另一个节点的输出（如checkpoint.output[1]），也可以是原始值（如latent.width = 512）。
3. 输出索引：output[0],output[1]代表节点的第几个输出端口。具体哪个索引对应什么，需要查阅ComfyUI的节点定义。对于CheckpointLoaderSimple，通常是[0]: MODEL, [1]: CLIP, [2]: VAE。
4. 异步操作：ComfyUI的API交互是异步的，因此我们使用asyncio。claw.queue_prompt(wf)将工作流提交到ComfyUI的执行队列，并返回一个任务ID。claw.wait_for_images(prompt_id)会阻塞等待，直到该任务执行完毕并返回生成的图片数据。
5. 运行脚本：在终端执行python first_claw.py。确保你的ComfyUI服务器正在运行，并且模型路径下有指定的v1-5-pruned-emaonly.safetensors文件（或其他你有的模型）。脚本运行后，你会看到ComfyUI的Web界面自动刷新，出现了你代码定义的节点图，并开始执行。最终，图片会保存在脚本所在目录。

实操心得：第一次运行时，最常见的错误是模型文件路径不对或节点类型名写错。建议先在ComfyUI图形界面手动拖出一个简单流程，观察其节点类型名和连接方式，再对应到代码中。ComfyClaw的节点类型名必须与ComfyUI内部注册的名称完全一致，区分大小写。

4. 进阶技巧：构建复杂与动态工作流

掌握了基础之后，我们可以探索ComfyClaw更强大的能力，用于构建真正复杂和动态的工作流。

4.1 节点分组与复用：打造自己的“宏”

当你的工作流变得复杂时，某些节点组合会反复出现。例如，一个标准的“文生图”链：加载模型、编码提示词、创建潜变量、采样、解码。我们可以将其封装成一个函数，实现复用。

def create_text_to_image_chain(wf, model_name, positive_prompt, negative_prompt, width=512, height=512, seed=None): """创建一个可复用的文生图节点链，并返回输出图片的节点引用""" import random if seed is None: seed = random.randint(0, 2**32 - 1) checkpoint = wf.add_node("CheckpointLoaderSimple") checkpoint.ckpt_name = model_name clip_pos = wf.add_node("CLIPTextEncode") clip_pos.text = positive_prompt clip_pos.clip = checkpoint.output[1] clip_neg = wf.add_node("CLIPTextEncode") clip_neg.text = negative_prompt clip_neg.clip = checkpoint.output[1] latent = wf.add_node("EmptyLatentImage") latent.width = width latent.height = height latent.batch_size = 1 sampler = wf.add_node("KSampler") sampler.seed = seed sampler.steps = 20 sampler.cfg = 7.5 sampler.sampler_name = "euler" sampler.scheduler = "normal" sampler.denoise = 1.0 sampler.model = checkpoint.output[0] sampler.positive = clip_pos.output[0] sampler.negative = clip_neg.output[0] sampler.latent_image = latent.output[0] vae_decode = wf.add_node("VAEDecode") vae_decode.vae = checkpoint.output[2] vae_decode.samples = sampler.output[0] # 返回解码后的图片节点，方便后续连接（如保存、后处理） return vae_decode # 使用示例 async def advanced_demo(): claw = ComfyClaw(server_address="127.0.0.1", port=8188) with claw.workflow() as wf: # 使用“宏”创建第一个图片 img1_node = create_text_to_image_chain( wf, model_name="sdXL_v10.safetensors", positive_prompt="a cyberpunk cityscape, neon lights, rain", negative_prompt="ugly, deformed", width=1024, height=768, seed=123 ) # 对第一张图进行后处理，例如使用一个简单的放大器 upscale_model = wf.add_node("UpscaleModelLoader") upscale_model.model_name = "4x_NMKD-Siax_200k.pth" image_upscale = wf.add_node("ImageUpscaleWithModel") image_upscale.upscale_model = upscale_model.output[0] image_upscale.image = img1_node.output[0] # 连接上一链的输出 # 保存放大后的图片 save = wf.add_node("SaveImage") save.images = image_upscale.output[0] save.filename_prefix = "upscaled_cyberpunk" # 执行工作流... prompt_id = await claw.queue_prompt(wf) images = await claw.wait_for_images(prompt_id) # ... 保存图片

这种封装极大地提升了代码的清晰度和可维护性，你可以像搭积木一样组合这些高级“函数”。

4.2 动态工作流与条件逻辑

ComfyClaw的真正威力在于可以用Python的全部能力来动态生成工作流。例如，根据输入列表批量生成不同参数的图片，或者实现条件分支。

async def batch_generate(): claw = ComfyClaw(server_address="127.0.0.1", port=8188) prompts = [ ("a serene landscape", "watercolor painting style"), ("a fierce dragon", "digital art, highly detailed"), ("an abstract pattern", "colorful, geometric") ] with claw.workflow() as wf: # 共享的模型加载器 checkpoint = wf.add_node("CheckpointLoaderSimple") checkpoint.ckpt_name = "dreamshaper_8.safetensors" # 为每个提示词创建独立的处理链 save_nodes = [] for i, (pos_prompt, style) in enumerate(prompts): # 动态组合提示词 full_prompt = f"{pos_prompt}, {style}" # 创建编码、采样、解码链 clip = wf.add_node("CLIPTextEncode", name=f"clip_{i}") clip.text = full_prompt clip.clip = checkpoint.output[1] latent = wf.add_node("EmptyLatentImage", name=f"latent_{i}") latent.width = 512 latent.height = 512 latent.batch_size = 1 sampler = wf.add_node("KSampler", name=f"sampler_{i}") sampler.model = checkpoint.output[0] sampler.positive = clip.output[0] sampler.seed = 1000 + i # 不同的种子 sampler.steps = 25 # ... 设置其他参数 vae_decode = wf.add_node("VAEDecode", name=f"decode_{i}") vae_decode.vae = checkpoint.output[2] vae_decode.samples = sampler.output[0] # 每个链单独保存 save = wf.add_node("SaveImage", name=f"save_{i}") save.images = vae_decode.output[0] save.filename_prefix = f"batch_output_{i}" save_nodes.append(save) # 这个工作流会一次性生成三张图片 prompt_id = await claw.queue_prompt(wf) images = await claw.wait_for_images(prompt_id) # images 将包含三张图片的数据

这个例子展示了如何利用for循环动态创建多个并行的节点链。你还可以结合if/else语句，根据条件决定创建哪些节点，实现真正动态的工作流拓扑。

4.3 与外部系统集成

ComfyClaw可以轻松集成到Web应用、自动化脚本或研究管道中。

from fastapi import FastAPI, HTTPException from pydantic import BaseModel import asyncio app = FastAPI() claw_instance = None # 在实际应用中需要妥善管理连接池 class GenerationRequest(BaseModel): prompt: str model: str = "v1-5-pruned-emaonly.safetensors" steps: int = 20 @app.on_event("startup") async def startup_event(): global claw_instance claw_instance = ComfyClaw(server_address="127.0.0.1", port=8188) # 可以预先建立连接等 @app.post("/generate") async def generate_image(request: GenerationRequest): try: async with claw_instance.workflow() as wf: checkpoint = wf.add_node("CheckpointLoaderSimple") checkpoint.ckpt_name = request.model # ... 构建工作流，使用 request.prompt, request.steps 等参数 save = wf.add_node("SaveImage") save.filename_prefix = "api_output" # ... 连接节点 prompt_id = await claw_instance.queue_prompt(wf) images = await claw_instance.wait_for_images(prompt_id) if images: # 通常将图片转为base64或保存到对象存储，返回URL image_data, _ = images[0] import base64 b64_image = base64.b64encode(image_data).decode('utf-8') return {"status": "success", "image_data": b64_image} else: return {"status": "error", "message": "No image generated"} except Exception as e: raise HTTPException(status_code=500, detail=str(e))

这样，你就拥有了一个可以通过HTTP API调用的AI图像生成服务后端，前端只需发送一个简单的JSON请求。

5. 避坑指南与性能优化

在实际使用ComfyClaw的过程中，我踩过不少坑，也总结出一些优化经验。

5.1 常见问题与排查

问题1：NodeNotFoundError或节点类型错误

• 现象：运行脚本时报错，提示找不到节点类型。
• 原因：ComfyUI的节点类型名拼写错误，或者你使用的自定义节点（Custom Node）没有在ComfyUI中正确安装/加载。
• 解决：
  1. 在ComfyUI图形界面，打开“节点管理”或直接拖出该节点，查看其精确的类别名称。
  2. 确保自定义节点的Python包已安装在ComfyUI的Python环境中，并且ComfyUI已重启加载。
  3. ComfyClaw只能操作ComfyUI服务器当前已加载的节点。

问题2：连接类型不匹配

• 现象：工作流提交后，ComfyUI界面显示节点连接处有红色错误提示，或者执行失败。
• 原因：代码中将一个输出类型连接到了不兼容的输入类型上。例如，把MODEL输出连到了CLIP输入。
• 解决：
  1. 在图形界面手动连接一次，观察端口颜色和提示。ComfyUI中不同数据类型通常有不同颜色。
  2. 仔细查阅节点文档，确认每个输出端口 (output[0],output[1]...) 对应的数据类型。
  3. 利用ComfyClaw可能提供的类型提示功能（如果版本支持）。

问题3：工作流执行成功但没收到图片

• 现象：wait_for_images返回空列表，但ComfyUI界面显示执行完成了。
• 原因：SaveImage节点可能没有被正确连接到最终输出，或者SaveImage节点本身没有被ComfyClaw标记为需要获取结果的输出节点。
• 解决：
  1. 确保你的工作流中至少有一个SaveImage节点（或PreviewImage等有图像输出的节点），并且其输入正确连接到了图像数据流。
  2. ComfyClaw的wait_for_images方法默认会收集工作流中所有SaveImage节点的输出。确保它被包含在工作流中。
  3. 在ComfyUI的“设置”中，检查输出目录权限是否正确。

问题4：API连接超时或失败

• 现象：无法连接到127.0.0.1:8188。
• 原因：ComfyUI服务器未启动，或启动时未使用--listen参数；防火墙或网络策略阻止了连接。
• 解决：
  1. 确认ComfyUI进程正在运行，并检查启动命令是否包含--listen。
  2. 尝试在浏览器中访问http://localhost:8188，看ComfyUI界面是否能打开。
  3. 如果ComfyUI和脚本不在同一台机器，需要配置正确的IP和端口，并确保网络可达。

5.2 性能优化与最佳实践

1. 复用连接与工作流对象：避免在循环中频繁创建和销毁ComfyClaw对象。应该创建一个实例，然后复用。对于相似的工作流，可以构建一个基础工作流模板，然后只修改其中变化的参数（如提示词、种子），而不是每次都从头构建整个图。

2. 异步并发处理：ComfyClaw基于异步IO。如果你需要同时管理多个生成任务，请使用asyncio.gather等并发原语，而不是顺序等待，以充分利用资源。

   async def generate_many(prompt_list): tasks = [generate_single(prompt) for prompt in prompt_list] results = await asyncio.gather(*tasks, return_exceptions=True) # 处理结果

3. 合理设置超时：在调用wait_for_images时，对于步骤多、分辨率高的任务，需要设置合理的超时时间，避免脚本无限期等待。

   try: images = await asyncio.wait_for(claw.wait_for_images(prompt_id), timeout=300) # 5分钟超时 except asyncio.TimeoutError: print("生成任务超时")

4. 利用工作流历史/缓存：对于完全相同的节点图（仅参数不同），ComfyUI内部可能有优化。但通过ComfyClaw每次提交的都是一个新的工作流定义。如果追求极致性能，可以考虑直接操作ComfyUI的更底层队列API，或者研究是否可以通过修改已有工作流的参数来复用。

5. 错误处理与重试：网络请求和AI生成本身可能不稳定。在生产环境中，务必对queue_prompt和wait_for_images添加重试机制和详细的错误日志记录。

6. 扩展应用场景与未来展望

ComfyClaw打开了ComfyUI程序化操控的大门，其应用场景远不止于简单的脚本生成。

场景一：自动化工作流测试与基准测试你可以编写脚本，用不同的采样器、CFG尺度、步数组合来测试同一组提示词，自动运行并收集结果图片和性能数据（生成时间、内存占用），用于模型或参数的量化评估。

场景二：构建复杂的多阶段生成管道例如，一个工作流可能包含：文生图 -> 图片放大 -> 人脸修复 -> 风格迁移 -> 最终输出。用ComfyClaw可以轻松地将这个多阶段管道脚本化，并允许在任意阶段插入条件判断（如图片质量评分过低则重试）。

场景三：集成到内容生成平台作为平台的后端引擎，接收用户简单的文本描述，后端用ComfyClaw动态组装包含特定风格Lora、ControlNet约束的复杂工作流，生成高度定制化的图片，而用户完全无需接触复杂的节点界面。

场景四：教育与研究对于教学，可以编写脚本逐步构建一个复杂工作流，每步添加注释，让学生清晰理解数据流向。对于研究，可以方便地实现算法，动态修改工作流结构（如循环迭代、条件分支），探索新的生成范式。

当前的局限与期待：ComfyClaw目前高度依赖对ComfyUI节点结构的了解，学习曲线存在。未来如果能提供更高级的、面向任务的抽象（如“创建一个图生图流程”），并集成节点搜索和类型提示，将会更加易用。此外，对ComfyUI“自定义节点”生态的兼容性也需要持续跟进。

从我个人的使用体验来看，ComfyClaw是ComfyUI高级用户和开发者的一个分水岭工具。它将可视化编排的灵活性与程序化自动化的力量结合在了一起。初期需要花费一些时间适应“用代码画图”的思维转换，但一旦掌握，你将获得前所未有的控制和效率，能够将ComfyUI的潜力在自动化工作流和集成应用中彻底释放出来。