OpenClaw与ComfyUI本地桥接服务部署指南

1. 项目概述：为什么需要 OpenClaw × ComfyUI 的本地桥接？

OpenClaw 和 ComfyUI，这两个名字最近在AI图像生成和智能体开发圈子里频繁撞车——不是因为它们同源，而是因为越来越多的开发者发现：光有 ComfyUI 的可视化工作流编排能力不够了，光有 OpenClaw 的技能调度与工具调用能力也不够了。真正卡住落地的最后一公里，是“怎么让 OpenClaw 的决策动作，精准、低延迟、可调试地驱动 ComfyUI 的节点执行”。这不是简单的 API 调用问题，而是一个涉及环境隔离、协议适配、状态同步、错误回溯的系统级桥接工程。

我去年帮三个团队做过类似集成，最典型的一个场景是：某工业设计团队想用 OpenClaw 自动解析客户邮件里的模糊需求（比如“把A部件的曲面过渡再柔和一点”），然后自动生成参数化建模指令，再触发 ComfyUI 调用 ControlNet + Depth 模型渲染多角度预览图，最后把结果自动发回邮件。整个链路里，OpenClaw 是“大脑”，ComfyUI 是“手+眼”，但中间缺一根稳定、可控、可观测的“神经束”——这就是本地桥接服务要解决的核心问题。

它不是“把 OpenClaw 装上 ComfyUI 插件就完事”的轻量级方案，而是构建一个独立运行、进程隔离、日志可追溯、配置可热更的桥接服务层。它不依赖公网 API（避免 token 管理、速率限制、隐私泄露），不强耦合于某个 ComfyUI 版本（兼容秋叶整合包、原生安装、Docker 部署），也不要求 OpenClaw 必须跑在 ROS2 环境下（Windows Companion、WSL2、Ubuntu 均可接入）。关键在于：桥接服务本身必须是“哑设备”——它只负责翻译、转发、记录、兜底，不参与任何业务逻辑判断。这点我踩过坑：早期直接在 OpenClaw 内部写 ComfyUI 请求模块，结果一升级 ComfyUI 接口就崩，调试时根本分不清是 OpenClaw 解析错了，还是 ComfyUI 返回格式变了，还是网络超时被吞了响应。

所以，“本地桥接部署服务”这七个字，字字都是硬骨头：

• “本地”意味着所有通信走 loopback 或 Unix socket，绕过防火墙、DNS、代理等中间环节；
• “桥接”不是单向调用，而是双向状态同步（比如 ComfyUI 渲染失败，必须原样反馈给 OpenClaw 并附带 error trace）；
• “部署服务”强调它是常驻进程（systemd / Windows Service / Docker 容器），而非临时脚本，具备重启恢复、资源隔离、健康检查能力。

如果你正在用秋叶 ComfyUI 整合包跑 Stable Diffusion 工作流，同时又在尝试用 OpenClaw 实现自动化任务编排，那这篇就是为你写的。它不讲概念，不堆术语，只告诉你：从零开始，如何在你的笔记本上，用最稳的方式，把这两套系统真正“接通”。

2. 整体架构设计与选型逻辑：为什么不用 HTTP 直连？为什么拒绝 WebSocket？

很多人第一反应是：“OpenClaw 调 ComfyUI 不就是发个 HTTP POST 吗？用 fetch 就完事。”——这确实是最低成本的启动方式，但也是最容易在第三天就崩溃的方案。我见过太多团队卡在“能跑通 demo，但上线就掉链子”的阶段，根源全出在架构选型上。下面拆解我们最终采用的三层桥接架构，以及每个环节的取舍理由。

2.1 核心分层：桥接服务 = 协议转换器 + 状态中继器 + 日志锚点

整个桥接服务不是单个程序，而是由三个协同组件构成：

1. Bridge Core（核心桥接器）：用 Python 编写，监听本地 TCP 端口（默认 8081），接收 OpenClaw 发来的结构化指令（JSON-RPC 2.0 格式），解析后转换为 ComfyUI 的 Queue Prompt API 所需的 payload，并注入必要的上下文字段（如client_id、prompt_id、workflow_name）；
2. ComfyUI Proxy（ComfyUI 代理层）：一个轻量 Node.js 进程（非 Express，用原生 http 模块），它不处理业务逻辑，只做三件事：a) 接收 Bridge Core 的请求并转发给本地 ComfyUI（http://127.0.0.1:8188）；b) 拦截 ComfyUI 的响应，提取prompt_id并建立映射表；c) 主动轮询 ComfyUI 的/history/{prompt_id}接口，将执行状态（queued/running/success/failed）实时推回 Bridge Core；
3. State Tracker（状态追踪器）：一个嵌入 Bridge Core 的内存数据库（SQLite in-memory mode），记录每条指令的全生命周期：接收时间、转换后 payload、发送时间、ComfyUI 返回码、历史查询轮询次数、最终状态、错误堆栈（如果失败）。这个表不是为了持久化，而是为了调试时能SELECT * FROM logs WHERE prompt_id = 'xxx'一键复盘。

提示：为什么不用 Redis 或 PostgreSQL？因为本地桥接服务的目标是“开箱即用”，增加外部依赖会显著抬高部署门槛。SQLite 内存模式足够支撑单机高并发（实测 50 QPS 下无锁争用），且无需额外安装服务。

2.2 协议选型：放弃 HTTP 直连，坚持 JSON-RPC over TCP

OpenClaw 默认使用 JSON-RPC 2.0 协议与外部服务通信（这是其 Skill System 的标准），而 ComfyUI 的官方 API 是 RESTful HTTP。如果强行让 OpenClaw 直接调 ComfyUI，就得在 OpenClaw 侧写 HTTP client，这带来三个致命问题：

• 超时不可控：ComfyUI 渲染一张图可能耗时 8~60 秒，HTTP client 的 timeout 设置成 10 秒会误判失败，设成 120 秒又导致 OpenClaw 主线程阻塞；
• 错误归因困难：HTTP 500 可能是 ComfyUI OOM，也可能是模型加载失败，还可能是插件冲突，OpenClaw 收到的只是字符串，无法结构化解析；
• 状态丢失：HTTP 是无状态协议，OpenClaw 发完请求就认为“已提交”，但实际 ComfyUI 可能卡在 queue、卡在 load model、卡在 VAE decode，OpenClaw 完全不知情。

所以我们强制规定：OpenClaw 只与 Bridge Core 通信，且仅使用 JSON-RPC over TCP。这样做的好处是：

• TCP 连接可设置 keepalive，避免长任务期间连接断开；
• JSON-RPC 的id字段天然支持请求-响应匹配，不怕并发乱序；
• 错误响应严格遵循{"jsonrpc":"2.0","error":{"code":-32602,"message":"Invalid params","data":"..."}}格式，OpenClaw 的 error handler 可直接提取data字段做分类重试；
• Bridge Core 在收到 OpenClaw 请求后，立即返回{"jsonrpc":"2.0","result":{"status":"accepted","prompt_id":"abc123"},"id":1}，告诉 OpenClaw “已收，正在处理”，不阻塞主线程。

2.3 环境适配：为什么 WSL2 是 Windows 用户的最优解？

搜索热词里反复出现wsl --status、sl2环境、openclaw windows companion，说明大量 Windows 用户卡在环境兼容性上。这里必须说清：不要在 Windows 原生环境下直接部署 ComfyUI + OpenClaw + Bridge Core 三件套。原因很现实：

• ComfyUI 的 PyTorch CUDA 驱动在 Windows 上极易与 OpenClaw 的 ROS2 Humble（依赖特定版本的 OpenSSL 和 libstdc++）冲突；
• Windows 的localhost解析有时指向 IPv6 ::1，有时指向 IPv4 127.0.0.1，TCP 连接偶尔失败；
• 秋叶整合包的 bat 脚本对路径空格、中文路径处理不健壮，Bridge Core 的日志路径一旦含中文就会报 UnicodeDecodeError。

我们的解决方案是：所有计算密集型服务（ComfyUI、Bridge Core）全部跑在 WSL2 Ubuntu 22.04 中，OpenClaw Windows Companion 作为客户端，通过localhost:8081访问 Bridge Core。实测下来，WSL2 的 localhost 网络性能几乎与原生 Ubuntu 无差别（ping <1ms），且完全规避了 Windows 的 DLL 冲突问题。部署时只需三步：

1. 在 PowerShell 中执行wsl --install（确保启用虚拟机平台）；
2. 安装 Ubuntu 22.04（微软商店下载）；
3. 在 WSL2 中用sudo apt install python3-pip nodejs npm装依赖，然后启动 Bridge Core 和 ComfyUI。

注意：WSL2 的 IP 地址每次重启会变，但localhost始终能正确映射到 WSL2 的 127.0.0.1，所以 OpenClaw Windows Companion 的配置里，host 填localhost即可，无需查 WSL2 IP。

2.4 安全边界：为什么禁止暴露 Bridge Core 到公网？

热词里出现openclaw无法安全验证，这其实是个伪命题——OpenClaw 本身不提供 Web UI，它的安全模型是基于进程间通信（IPC）或本地 TCP 的信任域模型。Bridge Core 也延续这一原则：默认只监听 127.0.0.1:8081，拒绝所有来自外部 IP 的连接。我们在 Bridge Core 的 TCP server 初始化代码里，明确指定host='127.0.0.1'，而不是'0.0.0.0'。

有人会问：“那我用手机访问 ComfyUI Web UI，能不能也用手机调 Bridge Core？”答案是否定的。Bridge Core 的设计哲学是：它只为 OpenClaw 服务，不是通用 API 网关。如果你需要移动端触发，正确做法是让手机先调用你自己的轻量 Web 服务（比如 Flask 写的 5 行接口），该服务再以本地 client 身份调用localhost:8081。这样既保持安全边界，又满足扩展需求。

3. 核心细节解析与实操要点：Bridge Core 的 7 个关键设计点

Bridge Core 看似只是一个中转程序，但实际编码时，有 7 个细节决定成败。这些不是文档里会写的“最佳实践”，而是我在三次线上故障复盘后，亲手加进代码里的硬核逻辑。

3.1 Prompt ID 的双重生成机制：避免 ComfyUI 的 ID 冲突

ComfyUI 的/prompt接口接受一个prompt_id参数，如果不传，它会自动生成 UUID。但问题来了：OpenClaw 发送的请求里，prompt_id是它自己生成的（用于后续状态查询），而 Bridge Core 如果直接透传，就可能出现两个不同 OpenClaw 实例用了同一个prompt_id，导致 ComfyUI 历史记录错乱。

我们的解法是：Bridge Core 生成一个内部 ID（bridge_id），同时保留 OpenClaw 的原始 ID（client_id），并将二者绑定。具体流程：

• OpenClaw 发来{"jsonrpc":"2.0","method":"queue_prompt","params":{"prompt_id":"cli_abc123",...}}；
• Bridge Core 生成bridge_id = "br_" + uuid.uuid4().hex[:8]；
• 构造 ComfyUI 请求时，"prompt_id": bridge_id；
• 同时在 State Tracker 的mapping表中插入INSERT INTO mapping (client_id, bridge_id) VALUES ('cli_abc123', 'br_xxx')；
• 当 ComfyUI 返回成功时，Bridge Core 查mapping表，把bridge_id对应的状态更新到client_id的记录里。

这样，OpenClaw 只需记住自己的cli_abc123，就能查到完整执行日志，而 ComfyUI 永远只看到唯一的br_xxx，彻底规避 ID 冲突。

3.2 ComfyUI 的 Model 加载兜底策略：防止“Missing Model”雪崩

ComfyUI 最常见的失败原因是Missing model: xxx.safetensors。如果 Bridge Core 直接把这类错误原样返回给 OpenClaw，OpenClaw 会认为“指令执行失败”，进而触发重试逻辑——结果就是连续 5 次请求都失败，ComfyUI 的 queue 被塞满，其他正常请求全被堵死。

我们的应对策略是：在 Bridge Core 层做模型存在性预检。原理很简单：ComfyUI 启动时，会在models/checkpoints/目录下生成一个model_list.json文件（如果没生成，Bridge Core 启动时主动扫描该目录并缓存）。当收到 OpenClaw 请求时，Bridge Core 先解析 payload 中的ckpt_name字段，检查该文件是否存在于models/checkpoints/下。如果不存在，立即返回结构化错误：

{ "jsonrpc": "2.0", "error": { "code": -32001, "message": "Model not found", "data": { "missing_model": "realisticVisionV5.safetensors", "available_models": ["juggernaut.safetensors", "dreamshaper.safetensors"] } }, "id": 1 }

OpenClaw 收到这个错误，就知道该换模型，而不是盲目重试。实测下来，这个预检将 ComfyUI 因模型缺失导致的无效排队降低了 92%。

3.3 大图生成的内存保护开关：防 ComfyUI OOM 杀死进程

ComfyUI 生成 1024x1024 图片时，显存占用峰值可达 12GB。如果用户连续提交 5 个高分辨率请求，ComfyUI 很可能被 Linux OOM Killer 杀死。Bridge Core 不能坐视不管，必须介入调控。

我们在 Bridge Core 中加入一个内存监控模块：启动时读取/proc/meminfo获取MemAvailable，设定阈值（比如剩余内存 < 3GB 时进入保护模式）。进入保护模式后：

• 拒绝新的高分辨率请求（width * height > 1024*1024），返回{"error":{"code":-32002,"message":"System memory low, please reduce image size"}}；
• 对已排队请求，插入{"inputs":{"seed": -1}}强制启用随机 seed，避免重复计算；
• 每 30 秒检查一次内存，恢复后自动退出保护模式。

这个开关不是万能的，但它把 ComfyUI 崩溃率从每周 3 次降到每月 1 次。

3.4 超时分级控制：区分“网络超时”与“渲染超时”

Bridge Core 对 ComfyUI 的调用，必须设置两层超时：

• 网络层超时（connect_timeout）：5 秒。如果 5 秒内连不上 ComfyUI（端口未开、进程挂了），立即返回{"error":{"code":-32003,"message":"ComfyUI unreachable"}}；
• 业务层超时（render_timeout）：60 秒。从 ComfyUI 返回200 OK开始计时，如果 60 秒内/history/{prompt_id}仍无status: success，则主动取消该 prompt（调用/queue的 cancel 接口），并标记为timeout。

关键点在于：网络超时必须短，业务超时必须长且可配置。我们在 Bridge Core 的 config.yaml 里暴露render_timeout: 60字段，用户可根据 GPU 性能自行调整（RTX 4090 可设 30，GTX 1660 可设 120）。

3.5 错误日志的上下文增强：让报错信息“会说话”

ComfyUI 的原始错误日志往往只有Traceback (most recent call last): ... RuntimeError: expected scalar type Half but found Float这种晦涩信息。Bridge Core 在捕获异常后，会自动附加三类上下文：

• 请求上下文：记录 OpenClaw 发来的原始 payload（脱敏处理，隐藏敏感字段如api_key）；
• 环境上下文：记录当前 Python 版本、PyTorch 版本、CUDA 版本、ComfyUI commit hash；
• 资源上下文：记录触发错误时的 GPU 显存占用（nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits）。

这样，当 OpenClaw 收到错误时，日志里会看到：

[ERROR] Prompt br_7f3a2e1d failed: RuntimeError: expected scalar type Half but found Float Context: - Request: {"prompt_id":"cli_abc123","workflow_name":"product_render_v2"} - Env: torch==2.1.0+cu118, comfyui@commit: a1b2c3d - GPU Mem: 11245 MB / 24576 MB

运维人员一眼就能判断：这是显存不足导致的精度降级失败，而不是代码 bug。

3.6 工作流名称的自动校验：防“找不到 workflow”静默失败

OpenClaw 的请求里常带"workflow_name": "marketing_banner"，期望 Bridge Core 加载workflows/marketing_banner.json。但如果该文件不存在，ComfyUI 默认会返回200 OK并执行一个空工作流，结果是生成一张纯黑图——OpenClaw 完全不知情。

Bridge Core 的对策是：在转发前，先检查workflows/目录下是否存在对应文件。如果不存在，直接返回：

{ "jsonrpc": "2.0", "error": { "code": -32004, "message": "Workflow not found", "data": { "requested": "marketing_banner", "available": ["product_render_v2", "logo_gen_v1"] } }, "id": 1 }

这个检查耗时 <1ms，却能避免 80% 的“结果不对但没报错”类问题。

3.7 Bridge Core 的热重载能力：改配置不用重启

Bridge Core 启动后，会监听config.yaml文件的修改事件（用watchdog库）。当检测到文件变更，自动 reload 配置，无需 kill 进程。特别有用的是log_level字段：开发时设debug，上线后切warning，全程无缝切换。

实操心得：热重载有个坑——如果config.yaml语法错误（比如少了个冒号），reload 会失败，但 Bridge Core 进程不会退出。我们加了守护逻辑：每次 reload 后，检查config.log_level是否等于预期值，不一致则打印Config reload failed, falling back to previous config并继续运行。宁可配置不变，也不能让服务宕机。

4. 实操过程与核心环节实现：从零部署的完整步骤清单

现在进入最硬核的部分：手把手带你完成本地桥接服务的部署。以下步骤已在 Windows 11 + WSL2 Ubuntu 22.04 + 秋叶 ComfyUI 整合包 v1.5.0 + OpenClaw Windows Companion v0.8.2 环境下 100% 验证通过。每个命令都标注了执行位置（WSL2 还是 Windows），避免混淆。

4.1 环境准备：WSL2 与基础依赖安装

在 Windows PowerShell 中执行（管理员权限）：

# 启用 WSL2（首次运行需重启） wsl --install # 安装完成后，启动 Ubuntu 22.04 wsl -d Ubuntu-22.04 # 在 WSL2 终端中执行： sudo apt update && sudo apt upgrade -y sudo apt install python3-pip python3-venv nodejs npm git curl -y

注意：不要在 WSL2 里装python3-dev或build-essential，Bridge Core 不需要编译 C 扩展，装了反而增加冲突风险。

4.2 ComfyUI 部署：使用秋叶整合包的最小化启动

仍在 WSL2 终端中操作：

# 创建工作目录 mkdir -p ~/comfyui-bridge cd ~/comfyui-bridge # 下载秋叶整合包（v1.5.0，适配 ComfyUI 0.3.10） curl -L https://github.com/Comfy-Org/ComfyUI/releases/download/0.3.10/comfyui_linux_portable.zip -o comfyui.zip unzip comfyui.zip rm comfyui.zip # 修改 ComfyUI 启动脚本，禁用浏览器自动打开 sed -i 's/--enable-cors-header//g' ./ComfyUI/startup.sh sed -i 's/xdg-open.*//g' ./ComfyUI/startup.sh # 启动 ComfyUI（后台运行，日志输出到 comfyui.log） nohup ./ComfyUI/startup.sh > comfyui.log 2>&1 & echo $! > comfyui.pid

验证 ComfyUI 是否启动成功：

# 检查端口占用 lsof -i :8188 # 应该看到 python3 进程监听 8188 端口 # 访问 http://localhost:8188 测试 Web UI（在 Windows 浏览器中打开）

4.3 Bridge Core 源码获取与配置初始化

继续在 WSL2 终端中：

# 克隆 Bridge Core 仓库（我们维护的稳定分支） git clone https://github.com/bridge-core/openclaw-comfyui-bridge.git cd openclaw-comfyui-bridge # 创建 Python 虚拟环境（隔离依赖） python3 -m venv venv source venv/bin/activate # 安装依赖（注意：requirements.txt 已锁定版本，避免兼容问题） pip install -r requirements.txt # 生成初始配置文件 cp config.example.yaml config.yaml

编辑config.yaml，关键字段说明：

# Bridge Core 自身监听地址 bridge: host: "127.0.0.1" port: 8081 log_level: "info" # ComfyUI 地址（必须是 WSL2 内部可访问的地址） comfyui: url: "http://127.0.0.1:8188" render_timeout: 60 # 根据你的 GPU 调整 # 工作流目录（OpenClaw 请求中的 workflow_name 会在此查找） workflows: path: "/home/yourname/comfyui-bridge/openclaw-comfyui-bridge/workflows" # 模型目录（用于预检模型存在性） models: checkpoints: "/home/yourname/comfyui-bridge/ComfyUI/models/checkpoints"

提示：yourname替换为你 WSL2 的用户名（用whoami查看）。路径必须绝对，不能用~。

4.4 工作流与模型目录准备：让 OpenClaw 能“找得到”

Bridge Core 需要两个目录：

• workflows/：存放.json格式的工作流文件，文件名即workflow_name；
• models/checkpoints/：存放.safetensors模型文件，Bridge Core 会扫描此目录生成可用模型列表。

创建 workflows 目录并放入示例工作流：

mkdir -p workflows # 下载一个最简工作流（仅 TextEncode + KSampler + SaveImage） curl -L https://raw.githubusercontent.com/bridge-core/openclaw-comfyui-bridge/main/examples/simple_text2img.json -o workflows/simple_text2img.json

验证模型目录：
确保~/comfyui-bridge/ComfyUI/models/checkpoints/下至少有一个.safetensors文件（秋叶整合包默认自带sd_xl_base_1.0.safetensors）。

4.5 Bridge Core 启动与健康检查

启动 Bridge Core（仍在 WSL2 终端）：

# 激活虚拟环境 source venv/bin/activate # 启动服务（后台运行） nohup python main.py > bridge.log 2>&1 & echo $! > bridge.pid # 检查是否监听 8081 端口 lsof -i :8081 # 应该看到 python3 进程

健康检查命令（在 WSL2 中执行）：

# 测试 Bridge Core 是否响应 curl -X POST http://127.0.0.1:8081 \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"ping","params":{},"id":1}' # 正确响应： # {"jsonrpc":"2.0","result":"pong","id":1} # 测试 ComfyUI 连通性（Bridge Core 会主动探测） tail -f bridge.log | grep "ComfyUI health check" # 应该看到 "ComfyUI is healthy" 日志

4.6 OpenClaw Windows Companion 配置：填对这 3 个字段

在 Windows 上，打开 OpenClaw Windows Companion 设置界面：

• Skill Configuration→ComfyUI Bridge→Host:localhost
• Port:8081
• Protocol:jsonrpc

注意：不要填http://localhost:8081，Bridge Core 是 TCP 服务，不是 HTTP 服务。填错会导致连接被拒绝。

测试技能调用：
在 OpenClaw 的 Skill Editor 中，新建一个 Skill，Method 选queue_prompt，Params 填：

{ "workflow_name": "simple_text2img", "prompt": "a cat wearing sunglasses, photorealistic", "width": 512, "height": 512 }

点击 Execute，观察 Bridge Core 日志（tail -f bridge.log）和 ComfyUI 日志（tail -f comfyui.log）。成功时，你会看到：

• Bridge Core 日志出现Received request for workflow simple_text2img；
• ComfyUI 日志出现Queued prompt；
• ComfyUI Web UI 的 Queue 面板显示新任务；
• 几秒后，output/目录生成图片。

4.7 日志与监控：如何快速定位问题？

Bridge Core 的日志是排障第一现场。关键日志文件位置：

• bridge.log：Bridge Core 主日志，记录所有请求、转发、错误；
• comfyui.log：ComfyUI 原生日志，记录模型加载、GPU 使用、渲染错误；
• ~/comfyui-bridge/openclaw-comfyui-bridge/logs/：Bridge Core 的 SQLite 数据库存档（每天一个.db文件）。

常用排查命令：

# 查看最近 10 条错误（Bridge Core） grep -i "error\|fail\|exception" bridge.log | tail -10 # 查看 ComfyUI 是否在加载模型（卡在这里说明模型路径错） grep "Loading checkpoint" comfyui.log | tail -5 # 查看 Bridge Core 的内存占用（确认没泄漏） ps aux | grep "main.py" | awk '{print $6/1024 " MB"}' # 查看 SQLite 数据库里最近的失败记录 sqlite3 logs/$(date +%Y%m%d).db "SELECT * FROM logs WHERE status='failed' ORDER BY created_at DESC LIMIT 5;"

5. 常见问题与排查技巧实录：那些文档里不会写的坑

部署过程中，90% 的问题都集中在几个固定环节。我把过去半年收集的 37 个真实案例，浓缩成这份速查表。每个问题都附带“现象→原因→解法→验证方式”，拒绝模糊描述。

5.1 OpenClaw 报错 “Connection refused”：不是端口没开，是 WSL2 网络没通

现象：
OpenClaw Windows Companion 显示Error: connect ECONNREFUSED 127.0.0.1:8081，但curl http://localhost:8081在 WSL2 里能通。

原因：
Windows 的localhost默认解析为 IPv6::1，而 Bridge Core 只监听 IPv4127.0.0.1。IPv6 连接被拒绝。

解法：
在 Windows 的C:\Windows\System32\drivers\etc\hosts文件末尾添加一行：

127.0.0.1 localhost

然后以管理员身份运行 PowerShell，执行：

ipconfig /flushdns

验证：
在 Windows 命令行执行ping localhost，如果返回Pinging localhost [127.0.0.1]，说明生效。

5.2 ComfyUI 返回 “Invalid prompt format”：不是 JSON 错，是 workflow_name 拼写错

现象：
Bridge Core 日志显示ComfyUI returned 400: Invalid prompt format，但 OpenClaw 发的 JSON 格式完全正确。

原因：
OpenClaw 请求里的workflow_name字段，对应workflows/目录下的文件名。如果文件名是simple_text2img.json，但请求里写"workflow_name": "simple_text2img"（漏了.json），Bridge Core 会找不到文件，返回空 payload 给 ComfyUI，触发格式错误。

解法：
Bridge Core 的workflows/目录下，文件名必须与workflow_name完全一致（包括后缀）。建议统一用.json结尾，请求里也带.json。

验证：
在 WSL2 中执行ls workflows/，确认文件名；再检查 OpenClaw 请求的workflow_name字段。

5.3 图片生成后 ComfyUI Web UI 不显示：不是保存失败，是 output 路径权限问题

现象：
Bridge Core 日志显示success，output/目录有图片文件，但 ComfyUI Web UI 的 Preview 面板一片空白。

原因：
ComfyUI 的 Web UI 静态文件服务，默认只读取ComfyUI/output/目录。如果 Bridge Core 把图片保存到~/comfyui-bridge/ComfyUI/output/，但 ComfyUI 进程启动时的--output-directory参数指向了别的路径（秋叶整合包有时会改），就会找不到。

解法：
在~/comfyui-bridge/ComfyUI/startup.sh中，找到python main.py这行，在后面加上：

--output-directory "/home/yourname/comfyui-bridge/ComfyUI/output"

然后重启 ComfyUI：

kill $(cat comfyui.pid) nohup ./ComfyUI/startup.sh > comfyui.log 2>&1 &

验证：
访问http://localhost:8188/output/，应该能看到图片列表。

5.4 Bridge Core 启动报错 “ModuleNotFoundError: No module named 'PIL'”：不是 Pillow 没装，是虚拟环境没激活

现象：
执行python main.py报ModuleNotFoundError，但pip list | grep pillow显示已安装。

原因：
你在全局 Python 环境下执行python main.py，而不是在venv虚拟环境中。全局环境没有安装 Bridge Core 的依赖。

解法：
务必执行source venv/bin/activate激活虚拟环境，再运行python main.py。

验证：
执行which python，应该返回/home/yourname/comfyui-bridge/openclaw-comfyui-bridge/venv/bin/python。

5.5 OpenClaw 调用后 ComfyUI 队列卡住：不是 Bridge Core 挂了，是 ComfyUI 的 queue_size 设太小

现象：
OpenClaw 成功提交请求，Bridge Core 日志显示forwarded to ComfyUI，但 ComfyUI Web UI 的 Queue 面板一直显示0/1，不执行。

原因：
ComfyUI 默认queue_size=1，如果已有任务在执行，新任务会排队。但 Bridge Core 的轮询逻辑假设队列是 FIFO，如果队列满了，它会一直等，导致 OpenClaw 认为超时。

解法：
修改~/comfyui-bridge/ComfyUI/main.py，找到def start_queue()函数，在self.queue = queue.Queue(maxsize=1)这行，把maxsize=1改成maxsize=5。

验证：
重启 ComfyUI，再提交 3 个请求，Queue 面板应显示3/5。

5.6 Bridge Core 日志疯狂刷 “ComfyUI health check failed”：不是 ComfyUI 挂了，是端口被占

现象：
bridge.log每秒打印ComfyUI health check failed，但curl http://127.0.0.1:8188能通。

原因：
ComfyUI 的/object_info接口（Bridge Core 用它做健康检查）需要 ComfyUI 完全启动后才响应。如果 Bridge Core 启动太快，在 ComfyUI 还没 ready