1. 项目概述在聊天中调用你的私人AI画室如果你和我一样既享受在Discord、Telegram或者iMessage里和朋友闲聊的轻松又痴迷于在本地部署的ComfyUI里折腾各种AI生图、换脸、风格迁移那你肯定也烦透了在两个世界间反复横跳的割裂感。一边是即时的聊天窗口另一边是复杂的节点工作流和参数调整生成一张图得先退出聊天打开浏览器调整半天再手动把图发回去流程繁琐得让人瞬间失去创作欲望。comfyui-bridge这个项目就是为了彻底打通这堵墙而生的。它的核心目标极其明确让你能在任何聊天窗口里用一句简单的自然语言指令直接驱动你本地那台可能装着RTX 4090、跑着复杂工作流的ComfyUI服务器并把生成好的图片自动送回聊天窗口。整个过程你的模型、你的数据、你的算力全都在你自己的硬件上没有内容审查没有API调用次数限制更没有云端服务的延迟和隐私顾虑。简单来说它是一套“聊天机器人 → 本地桥接服务 → ComfyUI”的自动化管道。我把它部署在了我的Windows主力机负责跑ComfyUI和常年开机的Mac Mini负责跑聊天机器人之间现在我可以在沙发上用手机给机器人发一句“给我画一个赛博朋克风格的猫咪黑客背景是下雨的霓虹都市”几分钟后图片就直接出现在聊天记录里。这种无缝的体验才是AI工具应该有的样子。2. 核心架构与设计思路拆解2.1 为什么是“桥接”而不是“集成”最初构思时我考虑过直接把ComfyUI的API调用逻辑写进聊天机器人比如OpenClaw的Skill里。但很快我就否定了这个方案原因有三职责分离与故障隔离ComfyUI本身可能不稳定尤其是加载大模型或复杂工作流时。如果调用逻辑直接写在机器人里一旦ComfyUI卡死或崩溃很可能连带导致机器人进程无响应或消息队列堵塞。将桥接服务独立出来它就成了一个可靠的“缓冲层”和“适配器”。机器人只负责接收用户指令并转发给桥接服务桥接服务负责与ComfyUI这个“怪兽”打交道处理轮询、超时、错误重试等脏活累活。即使ComfyUI挂了桥接服务可以返回明确的错误信息而机器人依然可以正常运行甚至可以将任务放入离线队列。协议与数据格式转换聊天机器人接收的是自然语言或带附件的多媒体消息而ComfyUI API接收的是结构化的JSON工作流。这个转换过程包含大量逻辑解析用户指令中的模式如--faceswap、提取图片、构建对应的工作流JSON、填充正确的节点参数等。这部分转换逻辑非常复杂且与具体的聊天平台协议无关。将其独立为桥接服务使得机器人端的Skill变得极其轻量只需要关注如何从特定聊天平台如Discord、Telegram提取消息和发送图片即可。多客户端支持与统一入口一个桥接服务可以同时为多个聊天机器人实例、甚至其他类型的客户端如一个简单的Web前端提供服务。它提供了一个统一的RESTful API任何能发送HTTP请求的客户端都可以调用。这大大提高了系统的可扩展性和复用性。因此最终的架构定型为三层[聊天客户端] --(自然语言/图片)-- [OpenClaw Skill] --(HTTP POST)-- [Bridge Server] --(ComfyUI API)-- [ComfyUI] ▲ │ [生成图片] --(下载)-- [Bridge Server] --(返回/推送)-- [聊天客户端]2.2 核心组件深度解析2.2.1 桥接服务器FastAPI应用的工程化实践桥接服务器 (server/bridge_server.py) 是整个系统的中枢。我选择FastAPI是因为它异步性能好、自动生成API文档并且类型提示对维护复杂逻辑帮助巨大。它的核心工作流程如下请求接收与验证通过/generate、/faceswap等端点接收来自Skill的multipart/form-data请求。这里除了文本参数最关键的是处理上传的图片文件。我使用了UploadFile类型来流式接收避免大图片一次性加载到内存。同时会进行基础验证比如检查必填参数、图片格式是否支持。工作流组装器这是桥接服务的“大脑”。根据传入的mode参数如txt2img,faceswap_pipeline它会从预定义的JSON模板库位于workflows/目录中加载对应的工作流。这些JSON模板不是静态的而是“模板的模板”。服务器会用Jinja2或简单的字符串替换将用户提供的prompt、negative_prompt、seed以及上传的图片经过Base64编码后动态注入到工作流JSON中对应的节点里。实操心得直接操作ComfyUI的JSON工作流非常容易出错因为节点ID (id) 和节点之间的连接 (links) 必须严格匹配。我的做法是先在ComfyUI桌面客户端手动搭建一个完美的工作流然后通过ComfyUI的API获取其完整的JSON定义将这个JSON保存为模板。在代码中我使用一个WorkflowBuilder类来负责查找和修改特定节点通过class_type和自定义的_meta.title属性来定位这比直接操作脆弱的数字ID要稳健得多。任务提交与状态轮询组装好的工作流通过ComfyUI的/prompt接口提交。ComfyUI会返回一个prompt_id。此后桥接服务会开启一个轮询循环定期调用/history/{prompt_id}来查询任务状态。这里需要处理各种异常网络超时、ComfyUI进程无响应、任务执行失败等。我设置了指数退避的重试机制并为轮询设置了总超时时间例如10分钟防止僵尸任务占用资源。结果获取与后处理当轮询检测到状态为success时从返回的历史记录中提取输出图片的节点信息和文件名。然后通过ComfyUI的/view接口或直接访问其输出目录来下载图片。此时可以进行一些后处理比如如果启用了--enhanced模式可能会调用额外的放大节点这里就需要在初始工作流中设计好串联。结果交付图片下载到桥接服务器本地后有两种方式返回给用户。一是通过API响应直接返回二进制流适合直接下载。但更常见的场景是Skill在提交任务后桥接服务立即返回一个prompt_id然后Skill或用户可以稍后通过/download/{prompt_id}这个独立端点来获取图片。这种方式更适用于生成时间较长的任务。另外我还集成了可选的Discord Webhook用于将所有生成的图片自动推送到一个审核频道方便在团队内部分享和复查。2.2.2 OpenClaw Skill智能的聊天界面代理Skill (skill/comfyui_generate.py) 是面向用户的界面。它的设计目标是对用户极其简单对异常极其健壮。自然语言解析它利用OpenClaw的指令解析能力将用户的消息如“/gen 一个宇航员在月球上遛狗 --enhanced”或“/faceswap -i [附件图片] --target 朋友的名字”解析成结构化的参数。这包括了提取命令、文本提示词、识别消息中的附件图片、解析提及的用户用于定向换脸等。客户端逻辑与队列机制Skill的核心是一个HTTP客户端负责将解析好的参数打包调用桥接服务器的对应API。但关键在于它的队列机制。在初始化时它会检查桥接服务器是否可达通过/health端点。如果不可达比如ComfyUI主机没开机它不会让用户命令失败而是会将整个请求包括图片附件序列化后保存到本地磁盘的一个队列目录中~/.openclaw/faceswap-queue/。同时它会友好地通知用户“任务已加入离线队列待服务器上线后自动处理”。质量门禁这是提升体验的关键。对于换脸这种容易出“恐怖谷”效果的操作盲目把结果发给用户很糟糕。Skill内置了两层检查空白图检测ReActor节点在未检测到人脸时有时会输出一个几乎空白的极小图片约2KB。Skill在收到图片后会首先检查文件大小如果小于阈值如10KB则自动触发一次重试。如果仍然失败则中止流程并给出明确错误“未检测到有效人脸”。视觉QA检查可选这是更高级的一层。如果本地运行了Ollama并安装了视觉模型如gemma3:12bSkill可以将生成的图片发送给视觉模型提问“这张图片里的人脸看起来自然吗有没有明显的扭曲、伪影或不协调” 如果模型回答“否”则可以将图片标记为“待审核”或者附上警告信息再发送给用户。这个功能会增加10-20秒的延迟但能显著过滤掉糟糕的产出。2.2.3 队列处理守护进程离线工作的保障queue_processor.py是一个独立的守护进程它定时扫描上述的离线队列目录。当它发现桥接服务器恢复在线时就会按顺序取出队列中的任务重新提交给桥接服务器处理并在完成后将结果发送给原始的目标聊天频道。这确保了即使用户在ComfyUI关机时提交了任务也不会丢失实现了“离线提交上线自动完成”的体验。3. 从零开始的部署与配置实战3.1 硬件与基础环境准备假设你有两台机器一台性能机Windows/Linux带NVIDIA GPU用于运行ComfyUI一台常开机机可以是Mac Mini、NAS或云服务器用于运行OpenClaw机器人。它们需要在同一局域网内互通。性能机ComfyUI Host操作系统Windows 10/11 或 Ubuntu 22.04 LTS。显卡至少6GB VRAM的NVIDIA GPU如RTX 3060。8GB或以上体验更佳能运行更大的模型。Python3.10或3.11。建议使用Miniconda或venv管理环境。ComfyUI从官方GitHub仓库克隆并安装。确保能通过http://localhost:8000正常访问其Web界面和API。常开机机Bot Host操作系统macOS、Linux或Windows均可。Python3.10。OpenClaw按照其官方文档安装并配置好确保能连接到你的目标聊天平台如Discord。3.2 ComfyUI的定制安装必备自定义节点ComfyUI的强大在于社区节点我们的工作流依赖其中几个关键节点。通过ComfyUI Manager安装是最简单的方式启动ComfyUI点击右下角的“Manager”按钮。切换到“Install Custom Nodes”标签页。在搜索框中依次搜索并安装以下节点ReActor用于人脸交换。搜索“ReActor”或使用地址https://github.com/Gourieff/comfyui-reactor-node。ComfyUI-IPAdapter-plus用于风格迁移和重绘。搜索“IPAdapter plus”或使用地址https://github.com/cubiq/ComfyUI_IPAdapter_plus。WAS Node Suite提供大量实用工具节点如图片加载、转换、文本处理等。搜索“WAS Node Suite”。ComfyUI-LivePortrait用于生成人物表情动画。搜索“LivePortrait”。rgthree-comfy一组提升工作流稳定性和效率的节点如“rgthree Context”。ComfyUI-GGUF可选如果你想运行FLUX.1等GGUF格式的模型需要安装此节点。安装后务必重启ComfyUI。3.3 模型准备选择你的艺术引擎节点是工具模型才是灵魂。你需要下载一些基础模型放到ComfyUI的models/checkpoints目录下。以下是我的推荐组合兼顾速度和质量模型名称主要用途特点下载来源示例RealVisXL V5.0 Lightning人物、肖像、通用场景基于SDXL Lightning架构出图速度极快5-10秒人物质感好。CivitAI (Model ID: 139562)Juggernaut XL Ragnarok建筑、物体、宏大场景细节丰富对比度强适合复杂场景和概念设计。CivitAI (Model ID: 133005)FLUX.1 Dev (GGUF Q5)极致真实感、摄影目前最先进的生图模型之一真实感无敌但速度慢VRAM占用高。HuggingFace (city96/FLUX.1-dev-gguf)4x-UltraSharp图片超分辨率放大用于--enhanced模式将图片放大4倍并增强细节。CivitAI (Model ID: 116225)IP-Adapter Plus Face风格迁移参考模型配合IP-Adapter Plus节点实现基于参考图的人像风格化。HuggingFace (h94/IP-Adapter)注意事项模型文件通常很大2-7GB。请确保你的硬盘有足够空间并且下载时注意来源可信。首次使用新模型时ComfyUI需要加载一段时间请耐心等待。3.4 桥接服务器的部署与配置现在我们在性能机上部署桥接服务。# 1. 克隆项目 git clone https://github.com/Bortlesboat/comfyui-bridge.git cd comfyui-bridge/server # 2. 创建Python虚拟环境推荐 python -m venv venv # Windows: venv\Scripts\activate # Linux/macOS: source venv/bin/activate # 3. 安装依赖 pip install -r requirements.txt # 主要包含fastapi, httpx, pillow, pydantic等 # 4. 复制并编辑环境配置文件 cp .env.example .env用文本编辑器打开新创建的.env文件这是配置的核心# .env 配置文件 COMFYUI_URLhttp://127.0.0.1:8000 # ComfyUI本机的API地址如果桥接服务与ComfyUI同机保持此值。 BRIDGE_HOST0.0.0.0 # 桥接服务绑定的IP0.0.0.0表示监听所有网络接口。 BRIDGE_PORT8100 # 桥接服务端口确保防火墙允许此端口。 # 可选Discord Webhook用于推送所有生成图片到指定频道便于审核。 # DISCORD_WEBHOOK_URLhttps://discord.com/api/webhooks/xxx/yyy # 可选设置默认模型如果不设置工作流JSON模板里指定的模型需存在。 # DEFAULT_CHECKPOINTrealvisxlV5.0_lightning.safetensors保存后启动桥接服务器python bridge_server.py如果看到类似INFO: Uvicorn running on http://0.0.0.0:8100的输出说明服务启动成功。你可以打开浏览器访问http://localhost:8100/health测试应该返回{status:ok,comfyui:reachable}。生产环境运行开发时这样启动没问题但长期运行建议使用进程管理工具。Linux (systemd)创建一个comfyui-bridge.service文件。Windows (NSSM)使用NSSM将其安装为Windows服务。通用 (PM2)如果你熟悉Node.js的PM2它也可以管理Python进程。pm2 start bridge_server.py --interpreter python --name comfyui-bridge3.5 OpenClaw Skill的安装与配置接下来在常开机机上配置OpenClaw Skill。复制Skill文件将项目中的skill/目录整个复制到OpenClaw的技能目录下。OpenClaw的技能目录通常位于~/moltbot/skills/或安装目录的skills/文件夹内。cp -r /path/to/comfyui-bridge/skill/ ~/moltbot/skills/comfyui-bridge/配置环境变量需要让Skill知道桥接服务器在哪里。在运行OpenClaw的环境中设置变量# Linux/macOS: 可以添加到 ~/.bashrc 或 ~/.zshrc然后 source export COMFYUI_BRIDGE_URLhttp://[性能机的局域网IP]:8100 # 例如export COMFYUI_BRIDGE_URLhttp://192.168.1.100:8100 # Windows (PowerShell): $env:COMFYUI_BRIDGE_URLhttp://192.168.1.100:8100关键点这里的IP地址必须是性能机在局域网中的IP而不是127.0.0.1因为OpenClaw运行在另一台机器上。安装Skill依赖进入Skill目录安装其所需的Python包。cd ~/moltbot/skills/comfyui-bridge pip install -r requirements.txt # 通常包含requests, pillow, openai等配置OpenClaw编辑OpenClaw的配置文件可能是config.yaml或config.json确保它加载了这个新Skill。通常需要在技能列表中添加comfyui-bridge并可能需要配置一些技能特定的触发词或权限。重启OpenClaw使配置生效。3.6 验证全链路连通性完成以上步骤后进行端到端测试在常开机机上测试Skill是否能访问桥接服务curl http://192.168.1.100:8100/health应返回成功的JSON。在聊天软件中向你的OpenClaw机器人发送一条简单的测试指令例如/gen 一只戴着眼镜的柯基犬在看书如果一切正常你应该能在聊天窗口中看到机器人回复“任务已提交...”稍等片刻后生成的图片就会被发送出来。4. 八大生成模式详解与实操指南comfyui-bridge支持丰富的生成模式每种模式都对应一个精心调校的ComfyUI工作流。了解它们你才能发挥最大威力。4.1 文生图与图生图创作与修改的基石文生图 (--prompt): 最基础的模式。只需提供描述如--prompt “a serene landscape painting of a mountain lake at dawn, style of studio ghibli”。桥接服务会调用配置好的SDXL模型来生成。参数技巧善用--negative_prompt排除不想要的元素如“blurry, ugly, deformed hands”。--seed参数可以固定随机种子用于复现某次满意的结果。图生图 (-i--prompt--strength): 在现有图片基础上进行修改。你需要附加一张图片并提供修改提示词和强度值0-1。--strength 0.3表示轻微修改保留原图大部分结构和内容--strength 0.7则允许AI进行更大程度的重新想象。/gen -i [附件我的房间照片] --prompt “a cyberpunk neon-lit version of this room” --strength 0.64.2 换脸全家桶精准的身份替换这是项目的亮点之一提供了三种不同精度的换脸模式。基础换脸 (--faceswap): 最简单的1对1换脸。需要一张源人脸图片-i和一个包含目标人脸的图片通常从聊天上下文或附件获取。它会将源脸换到目标图片的所有人脸上。避坑指南如果目标图片中有多张脸它会默认换掉检测到的第一张脸结果可能不可控。对于多人照请使用定向换脸。定向换脸 (--targeted-faceswap): 在群像照片中只替换特定人物的脸。除了源脸图和目标图你还需要在聊天中“提及”那个人或者以某种方式指定目标例如描述“左边第二个男生”。Skill会尝试结合人脸检测和上下文信息来定位目标。/faceswap -i [附件我的新发型自拍] --target 小明 机器人会去寻找小明最近发的照片或者当前聊天中的图片换脸增强流水线 (--faceswap-pipeline): 这是质量最高的模式也是默认推荐的换脸方式。它不仅仅执行换脸还包含一个后续的“清理”阶段。这个阶段会使用一个轻量级的Img2Img流程以极低的去噪强度如0.15对换脸区域进行微调和融合能有效消除换脸边缘的色差和不协调感让结果更加自然。当然耗时也更长约30秒。4.3 LivePortrait让静态照片“活”起来这个模式利用了ComfyUI-LivePortrait节点可以让一张人物肖像照片做出指定的表情。/liveportrait -i [附件证件照] --expression-preset smile可用的预设表情包括smile,laugh,angry,surprise,sad,disgust等。它本质上是在驱动一个轻量级的人脸动画模型生成一个短暂的GIF或视频序列。对于创建动态头像或趣味表情包非常有用。4.4 风格迁移与重绘赋予图片新生命风格迁移 (--style-transfer): 根据一张风格参考图生成一张全新内容但具有相同艺术风格的图片。你需要提供内容描述 (--prompt) 和风格参考图 (--style-ref)。/style-transfer --prompt “a cat sitting on a windowsill” --style-ref [附件梵高星月夜画作]这背后使用的是IP-Adapter技术它能将风格参考图的视觉特征编码成一组“风格向量”然后引导扩散模型按照这个向量去生成新图。重绘 (--restyle): 在风格迁移的基础上更进一步它同时需要内容图、风格参考图和提示词。它的目标是保持内容图的基本构图和主体但将其渲染成指定的风格。强度参数 (--strength) 在这里控制风格化的程度。/restyle -i [附件我的生活照] --style-ref [附件水彩画风格] --prompt “keep the pose and background, apply watercolor style” --strength 0.84.5 增强模式一键提升画质--enhanced是一个全局修饰符可以附加到任何模式上如--faceswap-pipeline --enhanced。启用后它会在生成流程的最后自动添加两个节点Face Detailer: 对图片中的人脸进行局部重绘和细节增强让人脸皮肤质感、眼睛细节更清晰。4x-UltraSharp Upscaler: 将图片放大4倍并使用超分模型补充细节让图片更适合在大屏幕上观看或打印。这个模式会显著增加生成时间可能翻倍和VRAM占用但画质提升是立竿见影的特别适合用于生成最终成品。5. 高级配置、问题排查与性能调优5.1 环境变量与工作流模板深度定制.env文件是主要的配置入口但你还可以通过修改工作流JSON模板来深度定制行为。所有模板文件都位于server/workflows/目录下。修改默认模型打开txt2img_workflow.json搜索checkpoint或ckpt_name字段将其值改为你已下载的模型文件名不含路径。这样所有文生图请求都会默认使用这个模型。调整采样参数在模板中你可以找到KSampler或Sampler节点修改steps采样步数、cfg提示词相关性等参数来平衡速度与质量。步数越多细节越好但越慢。自定义输出尺寸查找EmptyLatentImage节点修改width和height。注意SDXL模型推荐使用1024x1024或相近比例修改尺寸可能影响出图效果。重要警告修改模板前务必先备份。错误的节点连接或参数可能导致工作流提交失败。建议每次只修改一个参数并通过桥接服务的/health和简单的生成请求进行测试。5.2 常见问题与排查清单部署和使用过程中你肯定会遇到问题。以下是一个快速排查指南问题现象可能原因排查步骤Skill报错无法连接到桥接服务1. 桥接服务未运行。2. 防火墙阻止了端口。3.COMFYUI_BRIDGE_URL环境变量设置错误。1. 在性能机上运行 netstat -an桥接服务报错无法连接到ComfyUI1. ComfyUI未运行。2. ComfyUI的--listen参数未设置无法远程访问。1. 在性能机浏览器访问http://localhost:8000。2. 启动ComfyUI时需添加--listen参数python main.py --listen。3. 检查.env中的COMFYUI_URL是否指向正确的地址如http://192.168.1.100:8000。任务提交成功但一直处于“排队”或“执行中”1. ComfyUI工作流有错误执行失败但未正确报告。2. VRAM不足模型加载失败。3. 自定义节点缺失或版本不兼容。1. 直接访问ComfyUI的Web界面 (:8000)查看“Queue”和“History”面板常有错误信息。2. 查看ComfyUI启动终端的日志输出。3. 尝试在ComfyUI界面手动运行相同的工作流看是否报错。换脸结果空白或扭曲1. 源脸或目标脸未正确检测。2. ReActor节点参数如人脸恢复模型codeformer权重设置不当。1. 确保图片人脸清晰、正对镜头、无过大遮挡。2. 在faceswap_workflow.json模板中调整ReActor节点的facedetection人脸检测模型和codeformer权重0-1越高修复力度越大通常0.5-0.8。3. 启用--faceswap-pipeline模式利用后续清理阶段改善效果。风格迁移效果不明显1. IP-Adapter模型未正确加载。2. 风格参考图特征不够鲜明。3. IP-Adapter权重参数太低。1. 确认ComfyUI/models/ipadapter/目录下有正确的模型文件如ip-adapter-plus-face_sdxl_vit-h.bin。2. 使用风格强烈的参考图如鲜明的油画、素描。3. 在style_transfer_workflow.json中找到IPAdapter节点增加weight值如从1.0提高到1.2。生成速度非常慢1. 使用了慢速模型如FLUX.1。2. 采样步数 (steps) 设置过高。3. 启用了--enhanced模式增加了放大步骤。4. GPU性能瓶颈或VRAM交换。1. 对于快速预览使用RealVisXL Lightning这类优化模型。2. 将steps从30降低到20或15质量损失可接受。3. 仅在最终成稿时使用--enhanced。4. 使用任务管理器或nvidia-smi监控GPU使用率考虑关闭其他占用GPU的程序。5.3 性能调优与资源管理VRAM管理这是本地生图的核心限制。如果你在生成大图1024x1024或使用FLUX.1时遇到CUDA out of memory错误可以在ComfyUI的设置中启用“VRAM Saver”模式。使用--medvram或--lowvram参数启动ComfyUI。考虑使用ComfyUI-GGUF节点运行量化后的GGUF模型它们对VRAM需求更低但速度会慢一些。队列管理桥接服务本身是轻量的但ComfyUI同时只能处理有限的任务通常1-2个。Skill的离线队列和桥接服务的请求队列可以缓冲任务但要注意堆积。定期检查/diagnostics端点或清理ComfyUI输出文件夹里的旧图片。网络优化如果图片传输慢尤其是原始大图确保你的局域网速度正常。桥接服务下载图片时如果图片很大如4K增强后的图可以考虑在返回前先进行有损压缩如转换为JPEG并调整质量但这需要修改桥接服务器代码。5.4 扩展思路添加你自己的生成模式这套系统的强大之处在于可扩展性。如果你想添加一个新的功能比如超分辨率、图片修复、特定LoRA风格只需要在ComfyUI中手动构建工作流在UI上拖拽节点调试到你满意为止。导出工作流JSON点击ComfyUI的“Save (API Format)”按钮下载JSON文件。创建模板将JSON文件放到server/workflows/目录命名为my_new_mode_workflow.json。修改桥接服务器在bridge_server.py中添加一个新的API端点如/my-new-mode并在该端点的处理函数中加载你的新模板并编写参数注入逻辑。修改Skill在comfyui_generate.py中添加对新指令如--my-new-mode的解析并将其映射到新的API端点。通过这种方式你可以将任何复杂的ComfyUI工作流封装成一个简单的聊天命令分享给你的朋友或团队成员。