给视觉 Agent 配 ComfyUI 生图技能：从 12 个技能到输出目录踩坑的完整记录

背景

2026-06-08，技能工厂架构师为专职视觉设计师 Agent「云天光」（design-yuntianguang）配置了全部图片相关技能。2026-09-27 20:35，为云天光接入 ComfyUI 生图工作流并排查输出目录陷阱。此后云天光的生图能力以本地 ComfyUI 为主路径：Z-Image-Turbo 负责日常快出图，Ideogram 4.0 负责封面与文字排版。

2026-09-27 晚上，继续给 ComfyUI 技能包接入第三个工作流：Qwen Image 2.1 GGUF。这条工作流定位是 40 步精细模式，出图质量高于 Turbo，适合对细节要求更高的封面和关键插图。

接入过程中发现一个隐蔽陷阱：run_workflow.py 的 --output-dir 参数并不等于 ComfyUI 服务端的真实 PNG 落盘位置。排查结果：ComfyUI 服务端固定输出到 /data/comfyui/output/，--output-dir 只保存 temp_workflow.json 工作流快照。这个认知偏差导致脚本此前只会打印误导性目录，最终图片要靠手动到 output 目录找。

会话中的完整闭环

以下是设计 Agent 会话里实际完成的工作链，按顺序拆解。

1. 工作流文件落盘

qwen_image_21_gguf.json 已保存到工作流目录：

/home/oklife/.hermes/skills/creative/comfyui/workflows/qwen_image_21_gguf.json

{< image src="/images/Code-Art-Studio-images/comfyui-image-skill-setup-for-openclaw-agent/illustrations/1.webp" alt=“三个工作流 JSON 文件：Z-Image-Turbo、Ideogram 4.0、Qwen Image 2.1 GGUF” width=“100%” >}

2. 脚本支持 Qwen 识别与参数映射

run_workflow.py 更新了以下能力：

• 识别 qwen_image_21_gguf 工作流并注入对应参数
• 原生分辨率 1600×900（latent 对齐后实际输出通常为 1600×896，属正常现象）
• 支持 prompt、seed、width、height、ratio、steps、cfg、sampler_name、scheduler
• 改为从 ComfyUI history 解析真实输出文件名，脚本末尾直接打印 Outputs: <filename>

3. 依赖检查通过

check_deps.py 返回 is_ready: true

4. 冒烟测试成功生成

最终测试命令：

python3 /home/oklife/.hermes/skills/creative/comfyui/scripts/run_workflow.py \
  --workflow /home/oklife/.hermes/skills/creative/comfyui/workflows/qwen_image_21_gguf.json \
  --args '{"prompt":"a red shield emblem on a dark background","ratio":"16:9","seed":-1}' \
  --output-dir /data/design-yuntianguang-workspace/comfyui-output

{< image src="/images/Code-Art-Studio-images/comfyui-image-skill-setup-for-openclaw-agent/illustrations/2.webp" alt=“终端输出：run_workflow.py 打印真实输出文件名” width=“100%” >}

生成的文件实际存在于 /data/comfyui/output/Qwen_image_2.1_GGUF_00024.png（2.3MB），不是 --output-dir 指向的目录。

5. 文档回填

AGENTS.md 中同步更新：

• 第 111 行附近写入实际默认输出目录说明
• 0.3 博客标准工作流补上「本地 ComfyUI 真实 PNG 落盘位置在 /data/comfyui/output/」
• 后处理步骤区分本地 ComfyUI（从 output 目录取图）与远程降级（URL 下载）
• 末尾加强提示：--output-dir 不是真实 PNG 输出目录

三层生图能力现状

按当前 AGENTS.md 的正式记录，云天光的生图能力分三层：

主路径：本地 ComfyUI

统一入口：

python3 ~/.hermes/skills/creative/comfyui/scripts/run_workflow.py \
  --workflow <workflow.json> \
  --args '<json 参数>' \
  --output-dir <目录>

实测时的完整命令见上文「冒烟测试」小节，此处为模板示意。

降级路径

• 本地 ComfyUI 不可达或脚本报错 → 降级到 agnes-image
• agnes-image 也失败 → 再降级到 step-image
• 禁止跳过这两层直接调用其他 API

强制规则

• 未指定模型时默认走 Z-Image-Turbo
• 只有明确说「用 Ideogram / 用 4.0」时才切换
• 每次只生成 1 张，禁止批量
• 输出原始 PNG 必须保留，再额外做一次 PIL Resize + WebP quality=95 后处理

{< image src="/images/Code-Art-Studio-images/comfyui-image-skill-setup-for-openclaw-agent/illustrations/3.webp" alt=“三层生图能力：ComfyUI 主路径与两级降级” width=“100%” >}

输出目录陷阱拆解

这是本次接入最值钱的排障结论。

现象：脚本执行成功、history 里能看到生成记录，但 --output-dir 目录下没有 PNG。

根因：

• run_workflow.py 的 --output-dir 只保存 temp_workflow.json，不控制 ComfyUI 服务端输出路径
• ComfyUI 服务端（本地 127.0.0.1:8188）把 PNG 固定写到 /data/comfyui/output/
• 之前脚本只打印 --output-dir 路径，误导使用者去错误目录找图

修复动作：

1. 脚本改为从 ComfyUI history 解析真实输出文件名并打印 Outputs: <filename>
2. AGENTS.md 明确写死：真实 PNG 落盘位置是 /data/comfyui/output/，按 filename_prefix 找最新文件
3. 博客后处理流程对应改成「先到 /data/comfyui/output/ 取 PNG，再 PIL Resize + WebP 转格式」

通用教训：任何封装 ComfyUI 的脚本，「客户端参数目录」和「服务端落盘目录」都可能不一致。接入新工作流后，第一件事不是跑图，而是核对「脚本打印的目录」与「磁盘上真实出现 PNG 的目录」是否同一处。

steps 参数规则：默认 25 步，指定 40 步才精细

接入过程中还发现另一个易错点：--args 里不传 steps 时，走的是工作流内置默认值，而不是「精细模式」。

qwen_image_21_gguf.json 内置默认 steps=25。25 步出图速度约为 40 步的一半，但含文字、标签的画面（如架构图卡片、终端画面）容易糊边出乱码；40 步精细采样文字渲染清晰完整，代价是耗时翻倍。

因此定下的规则：

• 用户说「生图用 Qwen」但没带步数 → 走默认 25 步
• 用户明确说「Qwen 40 步 / 精细 / 文字清晰无乱码」→ 显式传 "steps": 40
• 封面或关键插图含大量文字标签、且用户未指定步数时 → 主动建议升 40 步

这条规则已同步写入 design-yuntianguang 的 AGENTS.md（Qwen 工作流段）和 blog-pipeline SKILL.md（Phase 4 生图参数规则），避免下次再依赖默认值出图后才发现文字乱码。

会话插曲：用户多次催促

会话里用户连续追问「？」「好了没」「为什么一直光说不做」，说明 Agent 在收尾阶段出现了「已说计划、未执行动作」的反复。最终在用户明确不满后，Agent 停止口头确认，直接执行剩余两步（文档补写 + 最终冒烟测试）才真正闭环。

{< image src="/images/Code-Art-Studio-images/comfyui-image-skill-setup-for-openclaw-agent/illustrations/4.webp" alt=“会话插曲：从口头确认到直接执行” width=“100%” >}

这个插曲本身也是一个可复用经验：子 Agent 在收尾阶段应优先执行再汇报，而不是反复确认「我计划做」。对编排方（主会话）而言，给子 Agent 的任务描述里应明确「最后一步完成后直接给结论，不要二次确认」。

结论

1. 云天光的生图能力现在正式包含三个 ComfyUI 工作流：Z-Image-Turbo、Ideogram 4.0、Qwen Image 2.1 GGUF
2. --output-dir 陷阱已修复，脚本会直接打印真实输出文件名，AGENTS.md 已写死真实落盘目录
3. 三层降级链（ComfyUI → agnes-image → step-image）保持不变
4. 接入新工作流的标准动作五步缺一不可：落盘 JSON → 脚本参数映射 + check_deps → 冒烟测试 → 核对真实输出目录 → 文档回填

行动项

• 核对 /data/comfyui/output/ 中 Qwen 工作流产物的命名前缀与脚本打印是否一致
• 在下次 Phase 4 生图时按「5 分钟产物校验」规则验证 Qwen 工作流是否稳定
• 将「客户端参数目录 ≠ 服务端落盘目录」写入 blog-pipeline 技能文档，供所有接入 ComfyUI 的 Agent 参考