OpenClaw ComfyUI 集成与智能体配置全记录

背景

在 OpenClaw 智能体系统中，视觉设计师云天光（design-yuntianguang）是负责博客封面图、文内插图等视觉素材生成的智能体。此前，它依赖两个远程 API 进行图像生成：agnes-image（主路径）和 step-image（降级路径）。但这两个 API 存在严重问题：

• agnes-image：生图质量不错，但经常 502 超时，稳定性堪忧
• step-image：质量不稳定，生图几乎没法用，而且尺寸限制严格（只能 1024x1024、1360x768 等），每次都需要 PIL Resize 后处理

同时，系统中还运行着**oc-engineer（oc工程师）**智能体，负责处理用户的配置、排障、集成等工程技术任务。用户通过 oc-engineer 来协调整个 OpenClaw 系统的优化工作。

第一部分：ComfyUI 本地生图集成

1.1 确认 ComfyUI 运行状态

本机已部署了 ComfyUI 服务，运行在 http://127.0.0.1:8188，使用 ComfyUI Kitchen 模板引擎。用户在使用 ComfyUI 的 Z-Image-Turbo 工作流，这是一个基于 AuraFlow 架构的快速图像生成模型。

首先确认 ComfyUI 可以正常访问：

curl -s http://127.0.0.1:8188/system_stats

返回确认：ComfyUI 0.28.0 运行正常，配备 NVIDIA RTX 4070（12GB VRAM），PyTorch 2.13.0+CUDA 13.0。

1.2 提取用户的工作流

用户已在 ComfyUI 中通过 WebUI 配置了一个 Z-Image-Turbo 工作流模板。需要从 ComfyUI 的历史记录中提取该工作流的 API 格式 JSON：

# 查看执行历史
curl -s "http://127.0.0.1:8188/api/history"

# 提取具体工作流
curl -s "http://127.0.0.1:8188/api/history/{prompt_id}" | python3 -c "
import sys, json
data = json.load(sys.stdin)
for v in data.values():
    workflow = v['prompt'][2]  # 提取 API 格式工作流
    with open('workflows/z_image_turbo.json', 'w') as f:
        json.dump(workflow, f, indent=2)
"

1.3 依赖检查

ComfyUI 已有现成的 comfyui skill，位于 /home/oklife/.hermes/skills/creative/comfyui/，包含完整的脚本体系：

# 检查工作流依赖是否满足
cd /home/oklife/.hermes/skills/creative/comfyui
python3 scripts/check_deps.py workflows/z_image_turbo.json

返回 is_ready: true，10 个必需节点（CLIPLoader、CLIPTextEncode、KSampler、VAEDecode 等）全部就绪，3 个模型依赖（z_image_turbo_bf16.safetensors、ae.safetensors、qwen_3_4b.safetensors）均已安装。

1.4 Smoke Test

python3 scripts/run_workflow.py --workflow workflows/z_image_turbo.json \
  --args '{"prompt":"a red cat sitting on a bookshelf, warm light, 8k"}' \
  --output-dir /tmp/comfy_output

一次性通过，生成了 1024×1024 的测试图，文件 1.3MB。全链路通了。

1.5 参数提取

通过 extract_schema.py 提取工作流的可控参数：

{
  "parameters": {
    "prompt": {"node_id": "57:27", "field": "text", "type": "string"},
    "seed": {"node_id": "57:3", "field": "seed", "type": "int", "value": -1},
    "steps": {"node_id": "57:3", "field": "steps", "type": "int", "value": 8},
    "cfg": {"node_id": "57:3", "field": "cfg", "type": "float", "value": 1.0},
    "width": {"node_id": "57:13", "field": "width", "type": "int", "value": 1600},
    "height": {"node_id": "57:13", "field": "height", "type": "int", "value": 900},
    "sampler_name": {"node_id": "57:3", "field": "sampler_name", "type": "string"},
    "scheduler": {"node_id": "57:3", "field": "scheduler", "type": "string"}
  }
}

1.6 批量生成测试

跑了一个 6 张的批量测试，生成「雨夜都市书桌与电脑办公」无人物封面图系列：

python3 scripts/run_batch.py --workflow workflows/z_image_turbo.json \
  --args '{"prompt":"...", "width":1600, "height":900}' \
  --count 6 --randomize-seed --output-dir /tmp/comfy_output/rainy-office

6 张全部生成成功，尺寸 1600×896（模型 latent 对齐限制，900 被自动圆整到最接近可解码高度），seed 随机。

第二部分：配置视觉设计师云天光

2.1 方案选择

用户确认采用 B 方案：让画面设计智能体直接具备 exec 权限，不经过 oc-engineer 中转，直接调用 run_workflow.py 脚本。

2.2 修改 openclaw.json

1. 在 design-yuntianguang 的 skills 列表中添加 comfyui skill
2. 在 tools.alsoAllow 中添加 exec 权限

2.3 创建 Skill 符号链接

ComfyUI skill 原本在 /home/oklife/.hermes/skills/creative/comfyui/，而 OpenClaw 的 skill 发现机制只扫描 ~/.openclaw/skills/。需要创建符号链接：

ln -s /home/oklife/.hermes/skills/creative/comfyui /home/oklife/.openclaw/skills/comfyui

2.4 更新 AGENTS.md（三件套对齐）

AGENTS.md（行为指引）：

• 新增 ### 0.1 本地 ComfyUI 生图（主路径），明确修改为：
  • 执行约束：当前工作区已授予 exec，云天光可直接提交 ComfyUI 并下载结果
  • 失败降级：ComfyUI 不可达 / workflow 依赖缺失 / 执行报错时，降级到 agnes-image
• 同时保留 ### 0.2 远程 API 生图（降级路径） 和 ### 0.3 博客生图标准工作流

MEMORY.md（经验教训）：

• 更新「生图工具优先级」为：本地 ComfyUI → agnes-image → step-image
• 去掉 agnes_image_safe.py 旧主路径描述
• 保留禁止轮询、限流即降级、主动汇报等好习惯

TOOLS.md（工具说明）：

• 修正顶部优先级为 ComfyUI 主路径
• 修复原来 agnes-image / step-image 写反的 Bug（agns-image 的说明里写的 step-image 模型）
• 更新标准工作流为 8 步清晰顺序

2.5 新增技能与工具

用户还选择配置了更多技能：

第三部分：会话管理陷阱

3.1 问题发现

配置完成后，用户发现：即使更新了 AGENTS.md，云天光在实际运行时仍然没有调用 ComfyUI，而是继续使用 curl 直接调用 stepfun.com 的 API。

3.2 根因定位

AGENTS.md 只在 session 启动时作为 bootstrap 加载一次。正在运行的 session 不会重新读取它。

检查发现，云天光的主 session（agent:design-yuntianguang:main）从 21:02 开始运行，积累了 49K+ tokens 的上下文。所有 kb-writer 发来的任务都追加到同一个 session 中，模型看到的旧 bash 脚本（curl ... stepfun.com）形成了上下文惯性。

3.3 解决方案

方案 A：删除旧 session 文件（立即见效）

rm /home/oklife/.openclaw/agents/design-yuntianguang/sessions/{session_id}.jsonl

方案 B：修改 kb-writer 的生产链路（长期方案）

让 kb-writer 在向云天光发送生图任务时，使用 sessions_spawn 而非 sessions_send，确保每次任务都起新 session：

# 改前
sessions_send(agentId="design-yuntianguang", message="生成封面图...")

# 改后
sessions_spawn(runtime="subagent", agentId="design-yuntianguang",
               cleanup="keep", task="生成封面图...")

用户选择了 B 方案，修改 kb-writer 的 AGENTS.md 中的 D-Step 3（封面图生成）和 D-Step 4（文内插图生成）。

3.4 强制规则

为了确保模型不再跳过 ComfyUI，在云天光的 AGENTS.md 中添加了强制规则：

⚠️ 强制规则（必须遵守，禁止跳过）：

1. 第一步：执行 curl -s http://127.0.0.1:8188/system_stats 检查 ComfyUI 是否可达
2. 如果 ComfyUI 可达：必须使用 run_workflow.py 生图，禁止使用 agnes-image 或 step-image
3. 仅当 ComfyUI 不可达或报错时，才降级到 agnes-image
4. 仅当 agnes-image 也失败时，才降级到 step-image
5. 禁止直接 curl 调用 step-image API 绕过整条链路

3.5 验证

通过 sessions_spawn 向云天光发送测试任务，新 session 正确读取了更新后的 AGENTS.md：

• ✅ 检查 ComfyUI 可达 → 成功
• ✅ 调用 run_workflow.py（正确 JSON 格式）→ 成功
• ✅ PNG 1600×896 → Resize 到 1600×900 → WebP quality=95
• ✅ 输出 /tmp/comfy_test2/cover.webp（170KB，222KB 两个版本）

第四部分：模型 Fallback 配置修复

4.1 问题发现

在 kb-writer 子代理执行过程中，出现 403 配额耗尽错误。子代理的解析模型为 sensenova/deepseek-v4-flash，但 kb-writer 的 primary model 是 sapiens/agnes-2.0-flash。

4.2 根因

子代理启动时，主模型 sapiens/agnes-2.0-flash 不可用，自动 fallback 到了全局默认模型的 fallback 列表中的 sensenova/deepseek-v4-flash，而 sensenova 的 API quota 已耗尽。

// 全局默认模型 fallbacks（修复前）
{
  "fallbacks": [
    "longcat/LongCat-2.0",
    "sensenova/deepseek-v4-flash",  // 🚫 配额已耗尽
    "zai/glm-4.7-flash",
    "sensenova/sensenova-6.7-flash-lite",  // 🚫 同 provider
    "freellmapi/auto",
    "sapiens/agnes-1.5-flash"
  ]
}

4.3 修复

从 openclaw.json 的 agents.defaults.model.fallbacks 中移除两个 sensenova 模型，并重启 Gateway：

# 修改后
"fallbacks": [
  "longcat/LongCat-2.0",
  "zai/glm-4.7-flash",
  "freellmapi/auto",
  "sapiens/agnes-1.5-flash"
]

最终成果汇总

全部改动

云天光最终配置

skills: 30+ 项（含 comfyui, agnes-image, step-image, image-reader,
           add-watermark-to-pdf, ui-designer 等）
tools.alsoAllow: [exec, image, read, write, edit, web_fetch]
生图优先级：ComfyUI（主）→ agnes-image → step-image（降级）

生图顺序

1. 本地 ComfyUI：python3 run_workflow.py 直接跑 z_image_turbo.json
2. agnes-image：agnes_image.py generate（降级）
3. step-image：step_image.py generate（再降级）

结论

这次实践完整覆盖了 OpenClaw 智能体系统的几个核心运维场景：

1. 外部工具集成：将本地 ComfyUI 通过 skill 体系接入 OpenClaw
2. 智能体配置优化：AGENTS.md/MEMORY.md/TOOLS.md 三件套对齐
3. 会话生命周期管理：理解 main session 与 subagent session 的区别，避免 stale context
4. 模型 Fallback 策略：管理多 provider 的 fallback 链路，避免走到配额耗尽的模型

这些经验对于运行 OpenClaw 智能体系统的用户来说，具有通用参考价值。特别是「会话管理陷阱」——很多人在配置 OpenClaw 时都会遇到这个问题：AGENTS.md 更新了，但智能体行为没变，因为 session 没有重新加载 bootstrap。

参考来源

• OpenClaw 官方文档
• ComfyUI 项目
• ComfyUI Kitchen 模板引擎
• Z-Image-Turbo 模型

–全文完–

若你有故事想讲、有困惑想聊、或是想找个人说说心里话，甚至只是吐槽发泄一下情绪，都欢迎来找我聊聊：　　　《内容已折叠，点击展开》

希望我写的每一个字，成为我自己和某个人活下去、拼下去的力量。　　　　　　　　　　　　　　　　　　　　　《内容已折叠，点击展开》

“技术终归是工具，而我们一次次认真把问题理顺，守住的其实不只是页面样式和代码输出，还有那一点不愿被混乱打败的心气，是每一个深夜仍愿点灯前行的人。”

转载请注明来自https://oklife.me。