1. 项目概述与核心价值如果你和我一样在AI绘画和自动化工作流领域摸爬滚打了一段时间肯定对ComfyUI又爱又恨。爱的是它那无与伦比的灵活性和节点化编程带来的强大控制力恨的是每次想让AI智能体Agent来调用这些复杂的工作流时都得写一堆胶水代码处理那些繁琐的API调用和参数映射。更别提在多台不同配置的服务器之间管理这些工作流了简直是场噩梦。今天要聊的这个项目——ComfyUI Skills for OpenClaw就是专门为解决这个痛点而生的。它本质上是一个“翻译官”和“调度员”把ComfyUI里那些专业、复杂的工作流包装成一个个干净、标准化的“技能”Skill让OpenClaw、Hermes Agent、Claude Code这类AI智能体能够像调用一个普通函数一样轻松地生成图像、处理视频或者执行任何你定义好的自动化任务。这个项目的核心价值在于它建立了一套面向智能体的接口规范。它没有试图去改造ComfyUI本身而是聪明地在ComfyUI之上加了一个抽象层。这个抽象层做了三件关键事第一它通过一个命令行工具CLI提供了统一、稳定的调用入口智能体只需要执行一条简单的shell命令第二它引入了Schema映射机制让你可以精确地控制智能体能“看到”和“操作”哪些参数隐藏掉背后复杂的节点连线逻辑第三它内置了多服务器管理能力你可以把本地测试机、云端大显存GPU服务器、甚至是专门跑某个模型的机器统一管理起来智能体无需关心任务具体在哪执行。对于任何想要将AI绘画、视频生成等创意工作流集成到自动化Agent系统中的开发者或团队来说这无疑是一个能极大提升效率和可靠性的工具。2. 核心设计思路与架构拆解2.1 为什么是“技能”Skill而非“API封装”很多人的第一反应可能是给ComfyUI工作流写个简单的HTTP API包装不就行了这个想法很自然但实际做起来问题很多。首先每个工作流的输入输出千差万别你需要为每个工作流单独设计API接口和参数验证逻辑维护成本高。其次智能体尤其是代码生成型Agent直接操作原始的ComfyUI工作流JSON是极其脆弱和不稳定的节点ID的变动、自定义节点的缺失都会导致调用失败。ComfyUI Skills项目选择“技能”这个抽象是更贴近Agent使用场景的设计。一个“技能”具备几个关键特征自描述性通过schema.json文件明确声明了技能的名称、描述、所需参数类型、是否必需、说明以及对应的ComfyUI节点映射关系。这相当于给智能体提供了一份清晰的“函数说明书”。标准化调用无论底层是文生图、图生图还是超分辨率对智能体而言调用方式都是一致的comfyui-skill run server/workflow --args ‘{“prompt”: “...”}’。这极大地降低了智能体的学习成本。依赖与状态管理技能系统能主动检查运行所需的自定义节点和模型文件是否就位并能管理任务的提交、状态查询和历史记录这些都是单纯的API封装难以提供的治理能力。这种设计巧妙地借鉴了“函数即服务”FaaS和“插件系统”的思想将复杂的ComfyUI工作流封装成了一个个可发现、可调用、可管理的原子能力。2.2 核心架构CLI驱动与数据存储模型项目的架构非常清晰遵循了“CLI First”的原则。所有核心功能都通过一个独立的命令行工具comfyui-skill-cli来提供。这样做的好处是它不依赖任何特定的Web框架或运行时环境可以无缝集成到任何能执行Shell命令的Agent平台中。整个系统的数据流和存储结构可以这样理解[AI Agent] | (执行CLI命令) v [comfyui-skill-cli] | (读取配置和技能定义) v [Config Data Layer] ├── config.json # 服务器配置URL、启用状态、输出目录 ├── data/ # 技能仓库 │ ├── local/ # 对应“local”服务器的技能 │ │ ├── txt2img/ # 一个技能 │ │ │ ├── workflow.json # 原始的ComfyUI API格式工作流 │ │ │ ├── schema.json # 参数映射Schema │ │ │ └── history/ # 执行历史记录 │ │ └── upscale/ │ └── remote-gpu/ # 对应“remote-gpu”服务器的技能 | └── ... | | (根据server_id路由) v [Target ComfyUI Server] (http://host:port) | (执行工作流) v [Result] (图片/视频等) - 保存至配置的输出目录关键设计点解析命名空间隔离技能通过server_id/workflow_id的方式寻址。server_id对应config.json中定义的服务器这天然实现了技能的多租户和路由。比如你可以把测试用的轻量模型工作流放在local服务器把需要40GB显存的SDXL模型工作流放在remote-a100服务器。配置与数据分离config.json只管理服务器元信息具体的技能定义工作流和schema存放在data/目录下。这种分离使得备份、迁移和版本管理变得非常容易。你可以轻松地将整个data/目录打包复制到另一台机器上使用。历史记录每个技能目录下的history/文件夹会记录每次执行的参数和结果如生成的图片路径这对于调试、审计和生成效果的回溯非常有帮助。3. 从零开始的完整部署与配置实操纸上谈兵终觉浅我们来一步步把这个系统搭起来并配置一个实际的技能。我假设你已经在本地比如http://127.0.0.1:8188运行了一个ComfyUI服务。3.1 环境准备与CLI安装首先你需要一个Python 3.10的环境。我强烈推荐使用pipx来安装CLI工具因为它能为每个命令行应用创建独立的虚拟环境避免依赖冲突。# 安装pipx如果你还没有 python3 -m pip install --user pipx python3 -m pipx ensurepath # 重新打开终端使PATH生效 # 使用pipx安装comfyui-skill-cli pipx install comfyui-skill-cli # 验证安装 comfyui-skill --help如果看到帮助信息说明CLI工具安装成功。用pipx安装后comfyui-skill命令在任何目录下都可用。注意如果你习惯用pip也可以pip install comfyui-skill-cli但要注意全局Python环境的管理。后续升级命令分别为pipx upgrade comfyui-skill-cli和pip install -U comfyui-skill-cli。3.2 项目克隆与基础配置接下来我们需要克隆技能仓库。根据你使用的Agent平台克隆到对应的目录。这里以最通用的方式为后续手动或多种Agent使用为例我们创建一个独立的工作目录# 创建一个专门存放技能的项目目录 mkdir -p ~/my-agent-skills cd ~/my-agent-skills git clone https://github.com/HuangYuChuh/ComfyUI_Skills_OpenClaw.git comfyui-skills cd comfyui-skills现在初始化配置文件。项目提供了一个示例配置我们复制并修改它cp config.example.json config.json用你喜欢的文本编辑器打开config.json。一个最简化的、针对本地ComfyUI的配置如下{ servers: [ { id: local, name: My Local ComfyUI, url: http://127.0.0.1:8188, enabled: true, output_dir: ./outputs } ], default_server: local }id: 这是服务器的唯一标识符后续在技能路径中会用到如local/my-workflow。url: 你的ComfyUI服务器地址。确保ComfyUI正在运行且该地址可访问。output_dir: 工作流生成文件如图片的保存路径。这里用的是相对路径./outputs意味着文件会保存在项目根目录下的outputs文件夹里。你也可以指定绝对路径如/home/user/comfyui_outputs。保存配置文件后可以测试一下与ComfyUI服务器的连接comfyui-skill server status如果返回服务器状态为在线并且列出了可用的模型等信息说明配置成功。3.3 导入第一个工作流并创建技能这是最关键的一步。我们以一个最简单的文生图txt2img工作流为例。首先你需要在ComfyUI中搭建好一个可用的工作流并通过其“Save (API Format)”按钮导出为一个JSON文件例如my_txt2img.json。假设这个工作流有一个CLIP文本编码器节点节点ID 6字段text接收提示词和一个KSampler节点节点ID 3最后连接到一个Save Image节点节点ID 9。拿到my_txt2img.json文件后我们将其导入系统comfyui-skill workflow import /absolute/path/to/my_txt2img.json这里必须使用绝对路径。导入成功后CLI会做几件事在data/local/目录下创建一个以工作流文件名命名的文件夹例如data/local/my_txt2img/。将工作流JSON文件标准化并存入workflow.json。自动生成一个初始的schema.json文件其中包含了工作流中所有可映射的节点和字段。现在查看一下当前可用的技能列表comfyui-skill list你应该能看到一个名为local/my_txt2img的技能。但是这个自动生成的schema可能包含了太多参数比如种子、步数、采样器等我们通常需要对其进行编辑只暴露我们希望智能体控制的参数。3.4 深度配置编写精准的Schema映射打开data/local/my_txt2img/schema.json你会看到类似下面的结构{ description: Imported workflow: my_txt2img, enabled: true, parameters: { text_6: { node_id: 6, field: text, required: false, type: string, description: CLIPTextEncode.text }, seed_3: { node_id: 3, field: seed, required: false, type: number, description: KSampler.seed } // ... 可能还有其他很多参数 } }我们需要编辑这个文件使其更符合“技能”的语义。假设我们只想让智能体控制“正面提示词”和“图片尺寸”而固定其他参数如采样器为DPM 2M Karras步数为20CFG为7。编辑后的schema.json可能如下{ description: 一个使用SD1.5模型生成图像的文生图技能, enabled: true, parameters: { prompt: { node_id: 6, field: text, required: true, type: string, description: 描述你想要生成的图像的文本提示词 }, width: { node_id: 12, // 假设Empty Latent Image节点的ID是12 field: width, required: false, type: number, default: 512, description: 生成图像的宽度默认为512 }, height: { node_id: 12, field: height, required: false, type: number, default: 512, description: 生成图像的高度默认为512 } } }关键点解析description: 技能的描述帮助智能体理解这个技能是做什么的。enabled: 设为false可以临时禁用该技能不会出现在comfyui-skill list的结果中。parameters: 定义技能接口。每个参数属性node_id和field: 精确对应ComfyUI工作流JSON中的节点ID和字段名。如何查找最可靠的方法是打开ComfyUI的“Save (API Format)”JSON文件搜索节点类型如KSampler找到其id再看其inputs里包含的字段名。required: 该参数是否为必填。type: 参数类型 (string,number,boolean,array等)。智能体调用时会根据此类型进行校验。default: 可选默认值。如果调用时未提供此参数将使用默认值。description: 参数的人类可读描述对于智能体生成正确的调用参数至关重要。实操心得在定义schema时“少即是多”。一开始只暴露最核心、最易理解的参数如prompt,negative_prompt。复杂的参数如sampler_name,scheduler可以在技能描述里说明其固定值或者等智能体熟悉基础用法后再逐步开放。这能显著降低智能体调用出错的概率。3.5 依赖检查与安装在让智能体调用之前最后一步是检查工作流的依赖是否满足。ComfyUI工作流可能依赖特定的自定义节点或模型。comfyui-skill deps check local/my_txt2img这个命令会分析workflow.json列出缺失的自定义节点通过节点类型判断和模型文件通过模型路径判断。对于它支持自动安装的依赖主要是一些流行的自定义节点它会给出安装命令提示。例如如果提示缺少ComfyUI-Impact-Pack节点你可以根据提示使用项目提供的命令进行安装如果支持。对于不支持的节点或模型你需要手动到ComfyUI的custom_nodes文件夹下安装或者将模型文件放到正确的目录。确保所有依赖都解决后这个技能就准备就绪了。4. 技能调用、多服务器管理与Web UI实战4.1 技能调用同步与异步模式现在我们可以通过CLI手动测试技能模拟Agent的调用行为。同步执行run 这是最直接的调用方式CLI会提交任务并等待ComfyUI执行完成返回结果。comfyui-skill run local/my_txt2img --args {prompt: A majestic lion in the savannah, photorealistic, width: 768, height: 512}执行成功后CLI会输出生成图片的保存路径例如./outputs/my_txt2img_20240520_112233.png。所有输出文件都会保存在config.json中为该服务器定义的output_dir下并按技能名和时间戳组织避免覆盖。异步执行submitstatus 对于耗时较长的工作流如高清修复、视频生成更适合使用异步模式避免CLI长时间阻塞。# 提交任务立即返回一个prompt_id comfyui-skill submit local/my_txt2img --args {prompt: An intricate steampunk cityscape} # 输出类似Submitted. Prompt ID: 1234567890 # 使用返回的prompt_id查询状态 comfyui-skill status 1234567890status命令会返回任务的状态pending,executing,success,failed以及成功后的输出文件路径。4.2 构建多服务器技能矩阵真正的生产力来自于将不同的计算资源统一调度。假设你有以下环境本地笔记本local用于快速测试和轻量模型。远程工作站remote-ws拥有24GB显存适合运行SDXL等较大模型。云端A100实例cloud-a100拥有80GB显存专门用于训练或运行极耗资源的模型如FLUX。首先在config.json中添加所有服务器{ servers: [ { id: local, name: Local Laptop, url: http://127.0.0.1:8188, enabled: true, output_dir: ./outputs/local }, { id: remote-ws, name: Remote Workstation, url: http://192.168.1.100:8188, enabled: true, output_dir: ./outputs/remote-ws, api_key: your_comfyui_api_key_if_any // 如果服务器设置了API密钥 }, { id: cloud-a100, name: Cloud A100, url: https://your-cloud-comfyui.com, enabled: true, // 可以随时禁用某个服务器 output_dir: ./outputs/cloud-a100 } ], default_server: local }然后将不同的工作流部署到不同的服务器上。例如将sd15_basic.json导入到localcomfyui-skill workflow import sd15_basic.json --server local将sdxl_refiner.json导入到remote-wscomfyui-skill workflow import sdxl_refiner.json --server remote-ws将flux_dev.json导入到cloud-a100comfyui-skill workflow import flux_dev.json --server cloud-a100现在你的技能列表可能是这样的local/sd15_basic remote-ws/sdxl_refiner cloud-a100/flux_dev当智能体需要生成一个快速草图时它可以调用local/sd15_basic当需要高质量、大尺寸图片时调用remote-ws/sdxl_refiner当需要最新的FLUX模型生成复杂场景时调用cloud-a100/flux_dev。智能体完全无需感知背后的硬件差异。4.3 使用Web UI进行可视化配置与测试对于复杂的参数映射或者团队协作纯手写JSON文件容易出错。项目提供了一个可选的Web UI它是一个独立的本地Web应用用于可视化地管理服务器、导入工作流和编辑Schema。启动Web UI 在项目根目录下运行提供的脚本即可。脚本会自动处理Python虚拟环境和依赖。# macOS/Linux ./ui/run_ui.sh # Windows ui\run_ui.bat启动后在浏览器中访问http://localhost:18189。Web UI核心功能实战服务器管理在UI中添加、编辑、启用/禁用服务器比直接编辑config.json更直观。工作流导入与预览直接将ComfyUI导出的JSON文件拖拽到UI中上传。UI会解析工作流并以缩略图形式展示节点图方便你确认导入的是正确的工作流。可视化Schema编辑器这是UI最大的价值。你可以在节点图上直接点击某个节点如KSamplerUI会列出该节点的所有输入字段。你可以勾选想要暴露给Agent的字段并为其设置友好的参数名、描述、类型和默认值。所有操作都会实时生成对应的schema.json无需手动编写。技能测试在UI中配置好Schema后可以直接在界面上填写参数并点击“运行测试”。这会在你的ComfyUI服务器上实际执行一次并将结果如图片显示在UI中让你在交给Agent之前确保技能配置无误。重要提示Web UI只是一个配置和测试工具。所有配置最终都会保存为项目根目录下的config.json和data/文件夹里的文件。Agent实际调用时仍然是使用comfyui-skillCLI。这种设计保证了生产环境调用的稳定性和一致性。5. 与主流AI Agent平台的集成实践配置好的技能最终是为了被AI智能体调用。下面以几个主流平台为例说明集成方式。5.1 与OpenClaw集成OpenClaw期望技能存放在特定的目录。按照项目README的指导将技能仓库克隆到OpenClaw的技能目录cd ~/.openclaw/workspace/skills git clone https://github.com/HuangYuChuh/ComfyUI_Skills_OpenClaw.git comfyui-skill-openclaw cd comfyui-skill-openclaw # ... 后续的pipx安装、config配置、技能导入步骤与上文相同配置完成后OpenClaw在规划任务时会自动发现comfyui-skill-openclaw这个技能包并读取其data/目录下所有已启用的技能。当它需要生成图像时就会在内部构造出类似comfyui-skill run local/sd15_basic --args ‘{...}’的命令并执行。5.2 与Claude Code或Cursor等代码生成型Agent集成对于Claude Code、GitHub Copilot Chat或Cursor这类以代码编写和Shell操作为核心的Agent集成更为直接。你只需要确保技能仓库和CLI工具在Agent的运行环境中可用。在给Agent的上下文如系统提示词或项目文档中说明可用的技能列表和调用格式。例如你可以在系统提示词中加入可用的图像生成技能 - txt2img: 使用命令 comfyui-skill run local/txt2img --args ‘{prompt: 描述} 生成图像。 - upscale: 使用命令 comfyui-skill run local/upscale --args ‘{image_path: /path/to/image.png, scale: 2} 放大图像。当用户要求“生成一张星空下的城堡图片”时Agent就会自动生成并执行相应的CLI命令。5.3 与Hermes Agent集成Hermes Agent有自己官方的技能管理生态。该项目也提供了与之兼容的安装方式# 通过Hermes CLI安装如果该技能已上架官方仓库 hermes skills install comfyui-skill-openclaw # 或手动克隆到Hermes的技能目录 cd ~/.hermes/skills/creative git clone https://github.com/HuangYuChuh/ComfyUI_Skills_OpenClaw.git comfyui-skill-openclaw集成后Hermes Agent会将这些技能作为其“创意”类能力的一部分在对话中根据用户意图自动调用。6. 高级技巧、故障排查与经验总结6.1 高级技巧动态参数与条件逻辑有时一个技能可能需要根据某个输入参数动态改变工作流。虽然ComfyUI Skills本身不直接支持工作流逻辑的修改但你可以通过“技能组合”或“参数预处理”来实现。方案一创建多个变体技能。例如针对不同的宽高比预先在ComfyUI中创建好txt2img_portrait(512x768)、txt2img_landscape(768x512)、txt2img_square(512x512) 三个工作流并导入为三个独立的技能。让Agent根据需求选择调用哪一个。方案二在Schema中使用“隐藏”参数和固定节点。例如你的工作流里可以放一个“Primitive”节点来接收一个“风格”代码如1代表动漫2代表写实然后在Schema中暴露这个“style_code”参数。在ComfyUI工作流内部使用“Conditioning (Set)”或“CLIP Text Encode (Prompt)”等节点根据“style_code”的值来切换不同的正面提示词前缀。这样对Agent来说它只需要传递一个简单的数字代码。6.2 常见问题排查实录在实际使用中你可能会遇到以下问题这里是我的排查思路问题1执行命令后返回HTTP 400 Bad Request错误。原因A工作流JSON格式不对。确保是从ComfyUI界面使用“Save (API Format)”按钮导出的而不是“Save (JSON)”。后者是内部格式缺少API执行所需的信息。原因BSchema映射错误。检查schema.json中的node_id和field是否与当前workflow.json中的节点ID和字段名完全一致。ComfyUI重新加载工作流后节点ID可能会变。原因C参数类型不匹配。Schema中定义type为number但Agent传递的是字符串10。确保传递的JSON参数值类型正确。问题2命令执行成功但在输出目录找不到生成的图片。原因A工作流没有有效的输出节点。确认你的ComfyUI工作流末端连接了Save Image、Preview Image或VAE DecodeSave Image等能输出图像的节点。ComfyUI Skills依赖于这些输出节点来获取结果。原因B输出路径权限问题。检查config.json中output_dir对应的目录是否存在以及当前运行CLI的用户是否有写入权限。问题3deps check报告缺失大量自定义节点。原因使用了非官方或小众的自定义节点。CLI的依赖检查主要针对一些流行且支持自动安装的节点包如ComfyUI-Manager列出的。对于其他节点你需要手动进入ComfyUI的custom_nodes目录执行git clone对应仓库。重启ComfyUI服务器。如果节点依赖特定模型还需手动下载模型并放入对应目录。问题4多服务器环境下任务被提交到了错误的服务器。排查使用comfyui-skill server list确认所有服务器状态为enabled: true且连接正常。确认调用技能时使用的server_id正确。记住技能的全称是server_id/workflow_id。6.3 配置备份与迁移当你精心配置好一套技能后定期备份和迁移到新环境就很重要。备份# 导出当前所有配置服务器列表和技能定义 comfyui-skill config export --output ./my-skills-backup.json这个命令会生成一个包含所有服务器配置和data/目录下所有技能定义的JSON文件。注意这个备份不包含outputs/目录下的生成结果也不包含ComfyUI本体的模型文件。迁移到新机器在新机器上安装ComfyUI并配置好基础环境Python、自定义节点、模型。安装comfyui-skill-cli。克隆或创建技能项目目录。将备份文件my-skills-backup.json复制到新项目目录。执行导入# 先干跑检查是否有问题 comfyui-skill config import ./my-skills-backup.json --dry-run # 确认无误后实际导入 comfyui-skill config import ./my-skills-backup.json运行comfyui-skill deps check对所有技能进行检查并补全缺失的节点或模型。经过几个月的实际使用我个人最大的体会是前期花在设计和定义清晰、稳定的Schema上的时间后期会在Agent调用的成功率和效率上加倍回报回来。不要试图一次性暴露所有参数从最简单的用例开始让技能和Agent一起迭代成长。这个项目提供的CLI和Web UI工具链恰好支撑起了这种从原型到生产的平滑过渡让ComfyUI这个强大的引擎真正成为了AI智能体手中一颗指哪打哪的可靠棋子。