OpenClaw 和 ComfyUI 这两个词放在一起很多人第一反应是“又一个 AI 缝合怪项目”。但如果你真把 OpenClaw 当本地 AI 助手在跑又在本地部署了 ComfyUI 做图像生成很快就会意识到这两者之间天然缺了一段路OpenClaw 只擅长调用工具、编排动作和执行决策ComfyUI 只擅长接收工作流、在显卡上算图。想让助手说一句“帮我画一张图”就真的产出图片不能靠祈祷必须把它们桥接起来。最近我花了一个周末把整套 OpenClaw x ComfyUI 本地桥接部署服务跑通了中间踩了不少坑包括 Windows 下 WSL2 环境验证失败、ComfyUI 接口调用姿势不对、桥接服务端口冲突等这篇就把完整思路、部署步骤和排查经验一次性写清楚。这套方案适合什么人如果你手上有一块还过得去的 NVIDIA 显卡想把 AI 助手和本地出图能力打通不想每次生成图片都烧云端 API 积分也不希望把作品和提示词传到第三方服务那你就是目标读者。哪怕你之前没碰过 OpenClaw只要有一点 Python 基础和照着文档折腾的耐心也能跟着走完。1. 为什么要在本地把 OpenClaw 和 ComfyUI 桥接起来1.1 从一次“AI 画图助手”的需求说起我先说下我的实际场景。我在本地跑了一个 OpenClaw 实例用来处理一些日常自动化任务包括检索资料、生成文本、管理文件等。后来我觉得不够想让它具备图像生成能力于是装了 ComfyUI本地跑 SD 模型。结果发现一个很尴尬的问题ComfyUI 本身是一个带网页界面的引擎我需要手动在浏览器里拖节点、写提示词、点“执行”这和 OpenClaw 的“自动决策”完全是两套逻辑。OpenClaw 说白了是一个 Agent 运行时它能理解自然语言指令然后通过预先定义的 skill 或 tool 去执行具体动作。但图像生成不是它原生支持的动作除非我告诉它“你应该去请求某个 HTTP 接口把用户提供的提示词塞进一个标准格式然后拿到返回结果”。ComfyUI 恰好也有自己的 HTTP API只不过它的 API 格式是为前端工作流设计的背后是一大串节点连接关系不是一个简单的“我给你 prompt 你就还我一张图”。所以问题就变成了如何在 OpenClaw 和 ComfyUI 之间做一个翻译层让 OpenClaw 用极简参数发起请求让 ComfyUI 老老实实按预设工作流出图再让 OpenClaw 把结果路径拿回来。这个翻译层就是标题里的“本地桥接部署服务”。1.2 桥接层选型不是直连而是加一个适配器有人可能会问OpenClaw 不是支持自定义工具吗直接把 ComfyUI 的 API 封装成一个 OpenClaw 工具不就行了理论上可以但实际很难受。ComfyUI 的原生 API 有太多和业务无关的细节每个前端工作流对应一个巨型 JSON里面有 CheckpointLoader、CLIPTextEncode、VAEDecode、SaveImage 这些节点还有节点之间的连线关系。如果让 OpenClaw 直接拼这个 JSON语义会非常脆弱而且每次换模型、换采样器都要改 Agent 端的代码。我的做法是在中间加一个轻量级适配服务也就是所谓的桥接层。OpenClaw 只负责把“用户想要什么图”这个意图翻译成结构化请求桥接服务负责把结构化请求转换为 ComfyUI 能识别的工作流 JSON提交给 ComfyUI 的/prompt接口然后轮询生成结果最后把图片的访问路径或本地文件路径返回给 OpenClaw。OpenClaw 看到的是一个极简 API比如{ prompt: a cyberpunk cat on neon street, negative_prompt: blurry, low quality, width: 1024, height: 1024, steps: 25 }桥接服务的价值在于隔离复杂度。以后我想切换底模从 SD 1.5 换到 SDXL只需改桥接服务里的工作流模板OpenClaw 端一个字符都不用动。换采样器、调整 CFG、开启高清修复全都是桥接层的事。这是做项目时的典型思路能不把复杂性扩散到上游就不要扩散。1.3 本地桥接带来的好处与代价选择全部本地化最直接的好处是隐私。提示词和生成的图片不会离开你的电脑不会进任何云端队列也不用担心公司内网的数据外发问题。其次是成本只要硬件够用出图没有按张计费的焦虑随便试错不心疼。但代价也很明显你需要自己维护一个 Python 服务、处理 ComfyUI 的依赖和模型路径、调显卡参数还要面对 Windows 环境下各种奇怪的报错。我在部署过程中遇到最经典的一个报错就是 OpenClaw 启动时提示无法安全验证 WSL2 环境让我在 PowerShell 里运行wsl --status。这个坑后面单独讲但先提醒大家如果你打算在 Windows 上跑完整链路提前把 WSL2 状态检查一遍不要等到联调时才崩溃。2. 部署前环境准备Windows 下的边界条件2.1 先把 ComfyUI 跑起来整合包与裸安装怎么选桥接服务的下游是 ComfyUI所以第一步不是写代码而是先把 ComfyUI 稳定跑起来。国内很多朋友会直接下载秋叶整合包因为它自带 Python 环境、模型管理器、常用插件确实省事。我自己后来换成了手动安装原因是整合包的自带环境经常和我的其他 Python 项目打架而且新版整合包升级时容易把自定义节点搞乱。如果你只是想在 OpenClaw 和 ComfyUI 之间打通用整合包完全够。但有几个细节必须确认第一ComfyUI 的安装路径不能有中文和空格否则有些插件和模型加载逻辑会抽风第二模型要放在models/checkpoints目录下不同模型类型有各自的子目录第三启动命令不要只双击run_nvidia_gpu.bat你需要知道 ComfyUI 的可选启动参数特别是--listen和--port。我的启动命令大概是这样的python main.py --listen 127.0.0.1 --port 8188--listen 127.0.0.1表示只监听本机回环地址外部机器访问不到对本地桥接来说足够安全。如果后面想让局域网里其他机器也能访问 ComfyUI 的网页可以考虑改成--listen 0.0.0.0但这样会有暴露端口风险建议只在可控内网环境下使用并配合防火墙限制来源 IP。桥接服务同样只监听127.0.0.1这样即使 ComfyUI 对局域网开放底层的 Agent 调用面也不会暴露太多。2.2 OpenClaw 的 Windows 运行环境和 WSL2 的坑OpenClaw 在 Windows 上跑原生版本其实没问题但它的很多 skill 依赖 Unix 工具链所以官方文档里通常建议配合 WSL2 使用。这里有个非常经典的坑OpenClaw 启动时会做环境自检如果检测到 WSL2 状态异常会报类似“OpenClaw 无法安全验证 WSL2 环境”的错误然后提示你在 PowerShell 中运行wsl --status查看详细状态。我第一次遇到时报错信息里的单词还是sl2明显是 WSL2 被某些日志截断了容易让人摸不着头脑。解决方案是打开 PowerShell依次执行wsl --status wsl --list --verbose第一行命令会告诉你当前 WSL 版本和默认发行版状态第二行会列出所有已安装发行版以及它们的 WSL 版本。常见情况是电脑装了 Ubuntu 发行版但默认版本是 WSL 1或者虚拟化平台功能没开启导致 WSL 2 无法启动。处理方式一般是在 PowerShell 管理员模式运行wsl --set-default-version 2 wsl --shutdown如果wsl --status提示内核需要更新去微软官网下载 WSL2 Linux 内核更新包装完后再wsl --shutdown重启即可。这里我想多说一句很多人一看到 WSL 报错就急着改 Windows 功能其实先跑一遍wsl --status看具体原因会省很多时间错误提示里通常已经写了下一步该做什么。不过在部署桥接服务时我并不依赖 WSL2。原因很简单ComfyUI 和桥接服务都是 Windows 原生进程通过127.0.0.1通信完全没问题。OpenClaw 如果只是通过 HTTP 调用桥接服务的接口也不需要非要跑在 WSL 里。只有当 OpenClaw 需要执行 shell 命令类 skill而 Windows 自带命令行能力不够时才需要 WSL2。所以我的建议是能走原生就走原生别为了“看起来正统”给自己挖坑。3. 实操从零搭一个本地桥接服务3.1 找一个 ComfyUI API 工作流先手动验证在写桥接服务之前先得准备一份 ComfyUI 能执行的 API 格式工作流。这个工作流不是普通的前端 JSON而是以节点 ID 为键名、以节点类型为索引的扁平结构。最笨的办法是打开 ComfyUI 的网页界面随便拖一个基础文生图流程然后点击“保存API格式”会得到一个可以直接 POST 给/prompt接口的 JSON。我这里以最朴素的文生图工作流为例结构看起来像这样{ 3: { class_type: KSampler, inputs: { seed: 123456, steps: 25, cfg: 7, sampler_name: euler, scheduler: normal, denoise: 1, model: [4, 0], positive: [6, 0], negative: [7, 0], latent_image: [5, 0] } }, 4: { class_type: CheckpointLoaderSimple, inputs: { ckpt_name: v1-5-pruned-emaonly.safetensors } }, 5: { class_type: EmptyLatentImage, inputs: { width: 512, height: 512, batch_size: 1 } }, 6: { class_type: CLIPTextEncode, inputs: { text: a cat, clip: [4, 1] } }, 7: { class_type: CLIPTextEncode, inputs: { text: blurry, clip: [4, 1] } }, 8: { class_type: VAEDecode, inputs: { samples: [3, 0], vae: [4, 2] } }, 9: { class_type: SaveImage, inputs: { filename_prefix: OpenClaw, images: [8, 0] } } }先不要急着改代码直接用curl手动测试一次看接口是否通curl -X POST http://127.0.0.1:8188/prompt ^ -H Content-Type: application/json ^ -d {\prompt\: {...工作流JSON...}}如果一切正常响应会返回一个prompt_id。再用这个 ID 去查历史curl http://127.0.0.1:8188/history/{prompt_id}返回内容里能找到生成图片的文件名、子目录、类型。手动验证成功之后后面的桥接代码只是把这套流程自动化而已。3.2 写一个轻量桥接服务我选 Python 写桥接服务理由是离 ComfyUI 生态最近解析 JSON 也顺手。这里不推荐引入特别重的框架一个 FastAPI 或 Flask 足够。我用的是 FastAPI因为它自带请求校验和文档页面后期调试 OpenClaw 的调用特别方便。下面是一个极简可用的版本只实现了单个接口/generate收到 OpenClaw 传来的参数后拼出工作流 JSON 并提交给 ComfyUI然后轮询/history接口拿到图片信息import json import time import uuid import requests from fastapi import FastAPI from pydantic import BaseModel, Field app FastAPI(titleOpenClaw-ComfyUI Bridge) COMFYUI_URL http://127.0.0.1:8188 class GenerateRequest(BaseModel): prompt: str Field(..., description正向提示词) negative_prompt: str Field(blurry, low quality, description负向提示词) width: int Field(512, ge256, le2048) height: int Field(512, ge256, le2048) steps: int Field(25, ge1, le60) ckpt_name: str Field(v1-5-pruned-emaonly.safetensors, description底模文件名) def build_workflow(req: GenerateRequest) - dict: seed time.time_ns() % (2 ** 32) return { 3: { class_type: KSampler, inputs: { seed: seed, steps: req.steps, cfg: 7, sampler_name: euler, scheduler: normal, denoise: 1, model: [4, 0], positive: [6, 0], negative: [7, 0], latent_image: [5, 0] } }, 4: { class_type: CheckpointLoaderSimple, inputs: {ckpt_name: req.ckpt_name} }, 5: { class_type: EmptyLatentImage, inputs: {width: req.width, height: req.height, batch_size: 1} }, 6: { class_type: CLIPTextEncode, inputs: {text: req.prompt, clip: [4, 1]} }, 7: { class_type: CLIPTextEncode, inputs: {text: req.negative_prompt, clip: [4, 1]} }, 8: { class_type: VAEDecode, inputs: {samples: [3, 0], vae: [4, 2]} }, 9: { class_type: SaveImage, inputs: {filename_prefix: OpenClaw, images: [8, 0]} } } app.post(/generate) def generate_image(req: GenerateRequest): workflow build_workflow(req) client_id str(uuid.uuid4()) resp requests.post( f{COMFYUI_URL}/prompt, json{prompt: workflow, client_id: client_id}, timeout10 ) resp.raise_for_status() prompt_id resp.json().get(prompt_id) for _ in range(120): hist requests.get(f{COMFYUI_URL}/history/{prompt_id}, timeout10).json() if prompt_id in hist and hist[prompt_id].get(outputs): outputs hist[prompt_id][outputs] for node_id, output in outputs.items(): if images in output: img output[images][0] return { prompt_id: prompt_id, image: { filename: img[filename], subfolder: img[subfolder], type: img[type], url: f{COMFYUI_URL}/view?filename{img[filename]} fsubfolder{img[subfolder]}type{img[type]} } } time.sleep(1) return {error: timeout}启动桥接服务uvicorn bridge:app --host 127.0.0.1 --port 8787这里有几个细节值得说。第一client_id是随机生成的ComfyUI 用这个字段维持 WebSocket 连接和任务去重就算我们不用 WebSocket 监听进度带上它也更规范。第二轮询上限我设了 120 次每次间隔 1 秒如果 2 分钟还没出图大概率是显存爆了或模型加载失败不如早点返回超时错误让上层 Agent 去判断。第三返回给 OpenClaw 的图片地址是 ComfyUI 自带的/view接口这个地址只能本机访问外部机器拿到也没用但对本地部署来说正合适。3.3 把桥接服务注册成 OpenClaw 的 skill 或工具OpenClaw 的 skill 本质上是给 Agent 的一组工具函数描述核心是告诉模型“你能调用什么、需要哪些参数、请求发到哪里”。不同版本的 skill 格式略有差异但大体都是声明式描述。我这里用一个极简 JSON 示例表示把上面的桥接服务注册成一个名为generate_image的工具{ name: generate_image, description: Generate an image using local ComfyUI. Use this when user asks to draw, paint, or generate a picture., parameters: { type: object, properties: { prompt: {type: string, description: positive prompt in English}, negative_prompt: {type: string, description: negative prompt}, width: {type: integer, description: image width, default: 512}, height: {type: integer, description: image height, default: 512}, steps: {type: integer, description: sampling steps, default: 25} }, required: [prompt] }, url: http://127.0.0.1:8787/generate, method: POST }你需要在 OpenClaw 的 skills 目录下新建一个local_comfy目录把这段描述放进 skill 清单或SKILL.md里然后把url改成你桥接服务的实际地址。这样当用户在 OpenClaw 里说“帮我画一只戴着机械臂的猫”时LLM 会判断需要调用generate_image工具自动把用户需求转换成英文 prompt并顺手补上合理的默认参数。一个容易忽略的点是LLM 并不是真的“看得懂”桥接服务它靠的是工具描述里的description。所以 description 要写得具体最好包含触发场景。不要写“image generation tool”这种套话要写“Use this when user asks to draw, paint, create a picture, or wants a visual output”这样模型才能准确触发工具。3.4 联调与参数把握全部跑起来之后我习惯先直接向桥接服务发一个请求验证链路curl -X POST http://127.0.0.1:8787/generate ^ -H Content-Type: application/json ^ -d {\prompt\:\a cute robot dog in park\,\width\:512,\height\:512,\steps\:20}返回的 JSON 里如果有image.url字段说明 OpenClaw 到桥接服务的通路没问题。接着再从 OpenClaw 对话界面发起一次真正带意图的对话让它调用桥接 skill 出图。参数方面我踩过几个值得记录的坑。SD 1.5 系列的底模在512x512下表现正常但放到1024x1024经常会出现人物比例崩坏这是模型本身的问题不是桥接代码的问题。SDXL 则默认更适合1024x1024如果你桥接服务的默认分辨率还是 512出来的图会很糊。所以如果你的底模是 SDXL记得把默认width和height都改成 1024。步数也不是越多越好SD 1.5 常见 20 到 25 步超过 30 步收益递减SDXL 到 30 步左右也基本收敛。CFG 值不用开放给用户固定在 7 左右就好桥接层越少暴露参数越容易控制出图质量。4. 常见问题与排查技巧实录4.1 OpenClaw 报 WSL2 无法安全验证怎么处理这个问题我遇到时非常迷惑因为 OpenClaw 本体跑得好好的只是启动某个依赖 shell 的 skill 时突然弹窗说“OpenClaw 无法安全验证 WSL2 环境。请在 PowerShell 中运行wsl --status以解决报告的问题”。我当时第一反应是去重装 OpenClaw后来发现根本不是它的锅。正确的排查顺序是先在 PowerShell 里执行wsl --status看输出的默认版本是不是 WSL 2。如果不是执行wsl --set-default-version 2然后重启。如果输出显示“未安装适用于 Linux 的 Windows 子系统内核”去装 WSL2 内核更新包。如果输出显示虚拟化相关错误进“启用或关闭 Windows 功能”确认“虚拟机平台”已开启。这里有个小技巧wsl --list --verbose比wsl --list多一点状态信息能看到每个发行版是 Running 还是 Stopped以及它们各自的 WSL 版本。如果某个发行版还停在 WSL 1可以用wsl --set-version {发行版名} 2手动迁移迁移。迁移时间取决于根文件系统大小我迁移 Ubuntu 时用了大概两分钟期间不能关闭终端。4.2 图不生成提示词传不过去桥接服务刚写好时我最常遇到的情况是 OpenClaw 那边提示调用成功但 ComfyUI 没有任何反应。排查思路很简单先绕过 OpenClaw直接 curl 桥接服务看返回值。如果桥接服务自己都超时再看 ComfyUI 的控制台日志。日志里如果出现Error prompting或module json has no attribute之类基本是工作流 JSON 里节点 ID 或引用关系不对。另一个隐蔽问题是我在 FastAPI 里定义了prompt字段但 OpenClaw 发请求时把所有参数塞进了一个data字段里导致字段对不上桥接服务直接报 422。解决办法是看桥接服务的请求体日志确认实际收到的 JSON 结构和预期一致。建议在桥接服务里加一行请求体打印运行几轮确认没问题后再关掉。真实联调中90% 的问题都出在“字段名不一致”或“URL 末尾多了个斜杠”这种愚蠢细节上。ComfyUI 这边如果提示词传过去了但出图全黑或全灰先查负向提示词是否为空再看看是不是模型加载到了错误的精度模式。低显存机器如果开了--lowvram偶尔会出现输出质量异常这时候可以试着打开--force-fp16或--force-fp32手动固定精度。4.3 显卡显存相关硬性问题显存不足时 ComfyUI 不一定会直接崩溃更常见的是生成过程卡住很久然后报CUDA out of memory。桥接服务这边表现为轮询超时OpenClaw 收到一个 timeout 错误。处理方案有几个层次降低分辨率比如 SDXL 从 1024 降到 768显存占用立减启用--lowvram或--medvram启动参数让 ComfyUI 分阶段加载模型权重检查是不是同时开了多个 ComfyUI 进程Windows 下重复启动整合包很容易导致显存被两个进程瓜分换更小的模型比如 SD 1.5 的蒸馏版或 SDXL Turbo 这类少步数模型。我遇到过最奇葩的情况是显卡确实有 24GB 显存但被其他程序占了一半ComfyUI 依然报 OOM。所以排查 OOM 时先开任务管理器看“专用 GPU 内存”占用确认不是其他伴生程序抢显存。桥接服务的轮询逻辑也可以优化提交任务后立刻用 ComfyUI 的 WebSocket 监听进度一旦收到executing事件就知道真的在跑而不是傻等 120 秒。4.4 端口、路径、防火墙最容易翻车的细节桥接服务监听8787ComfyUI 监听8188看起来互不干扰但 Windows 下有个常见毛病是端口被 Hyper-V 保留区间占用。如果你启动 uvicorn 时发现端口起不来Windows 事件日志或命令行会有很明确的Permission denied提示。可以先查保留端口区间netsh interface ipv4 show excludedportrange protocoltcp如果 8787 正好在保留区间里换个端口就行别硬刚。另一个让我差点砸键盘的问题是 Python 的.venv环境和全局环境相互污染导致requests库版本不对桥接服务发起 ComfyUI 请求时 SSL 报错。解决方案很简单新建项目目录时就立刻python -m venv .venv之后的依赖全部从虚拟环境里装。路径方面ComfyUI 的模型路径中一旦有中文CheckpointLoaderSimple就找不到ckpt_name。如果是从网盘下来的秋叶整合包默认目录通常是ComfyUI_windows_portable很多人直接放在中文用户名目录下面模型加载必然出问题。我建议手动把模型路径整理清楚或者至少给extra_model_paths.yaml配好绝对路径。防火墙也值得一提。如果 OpenClaw 和桥接服务都在同一台机器、都用127.0.0.1就不会有防火墙拦截问题。如果你把 OpenClaw 跑在 WSL2 里而 WSL2 访问 Windows 宿主机时用的是虚拟网卡 IP不是127.0.0.1这时你必须在 firewalld 或 Windows Defender 防火墙里放行对应端口。所以我从一开始就建议 OpenClaw 也跑 Windows 原生版省掉一堆跨子网问题。想省事的话桥接服务统一监听127.0.0.1其他所有服务都走本机回环是最干净的拓扑。5. 实测体验、避坑心得与后续扩展全套跑通之后的体验确实舒服。我现在对 OpenClaw 说“画一只穿着宇航服在火星上看书的狐狸”它会在十几秒内返回一张本地生成的图图片路径直接挂在本机 ComfyUI 的/view接口上整个过程不经过任何外部服务。不过回到实际操作层面我发现有四个点必须提前考虑不然后期返工很痛苦。第一桥接服务不要和 OpenClaw 的配置混在一起。我一开始图省事把桥接代码放在 OpenClaw 的插件目录里后来发现 OpenClaw 升级会覆盖插件目录差点把桥接服务删了。正确做法是独立目录、独立虚拟环境、独立进程管理最好注册成一个 Windows 服务或开机自启任务。第二ComfyUI 的底模和采样器不要每次都在代码里写死第一次写死没关系但后期换模型时一定会手忙脚乱。可以在桥接服务里增加一个配置接口或者允许 OpenClaw 的请求参数覆盖ckpt_name我给 JSON Schema 里加了ckpt_name字段实测很方便。第三不要忽视 ComfyUI 自带的队列机制。多个 OpenClaw 请求同时进来时每个请求都会排队但桥接服务如果每次都创建一个新 prompt_id 去轮询有可能拿错历史记录。我在实测中加了一组“请求 ID 与 prompt_id 的映射表”类似一个简易缓存既方便查询历史也避免一个请求轮询到另一个请求的输出。第四图片生成完之后如果 OpenClaw 还需要对图片做进一步理解比如把图发给自己的多模态模型描述内容图片的本地路径反而比 URL 更实用。所以我又在桥接服务里增加了一个return_path开关默认返回 URL调试时切换成路径少绕很多弯。后续扩展的话一个是把本地 LLM 接进来。我目前让 OpenClaw 负责意图理解和工具调用但如果想让整个链路更私密、更离线可以把 OpenClaw 里负责对话理解的模型替换成本地 Ollama 或类似服务这样从“听懂用户”到“画出图片”全程不依赖外部接口。另一个是接入多显卡或集群场景OpenClaw 的桥接层本来就是一个 HTTP 服务上游可以变成多个 ComfyUI 节点的调度入口只要在桥接服务里加一层负载均衡策略即可。还有一个很实际的方向是给桥接服务加历史记录和画廊页OpenClaw 每次生成的图都留档后期按提示词检索比在文件夹里翻图片方便得多。这次部署让我最深刻的一个体会是本地 AI 工具链的难点通常不在单个组件而在组件之间的对齐成本。OpenClaw 自己的配置、ComfyUI 的工作流、桥接服务的字段定义每一层都有自己的上下文稍有不匹配就会变成一串很难看懂的报错。但只要把桥接层做成一个职责单一的适配器先把接口固定下来再回头调整内部实现整个系统反而变得很稳。如果你也在折腾类似的本地 Agent 加生图链路建议先跑通我上面的最小版本再慢慢加你自己的偏好少想一步到位先让链路通后面的一切都好说。