comfyui-skill-openclaw

ComfyUI Agent 技能

前置条件：安装 CLI：pip install -U comfyui-skill-cli。官方本地 Comfy MCP 为可选项，需要 MCP 功能时，请按照官方指南进行连接。所有 shell 命令都必须在本项目根目录（即此 SKILL.md 所在目录）中运行。

[!IMPORTANT] 目录敏感性：CLI 会从当前目录读取 config.json 和 data/。 运行任何命令前，你必须先 cd 到项目根目录。 现象：list 返回 []，或 server status 报告找不到 → 你当前所在目录不正确。

快速决策

• 存在匹配的已注册工作流 → 使用 CLI 执行流程（步骤 1-4）。这是重复、批量和对延迟敏感任务的默认方式。
• 请求没有匹配的工作流，或需要实时发现模板／模型／节点 → 使用官方本地 Comfy MCP。
• 用户提供了需要在真实环境中验证的原始工作流 → 使用 MCP validate_workflow；对于已注册工作流，使用 CLI run --validate。
• 用户要求安装节点、下载模型、重启、更新或切换版本 → 仅在说明影响并获得确认后使用 MCP。
• 用户说“生成图片／画一张图” → 先检查已注册工作流；如果没有合适的工作流，则发现当前的 MCP 模板，不要猜测模型名称。
• 用户说“导入工作流／添加工作流” → comfyui-skill --json workflow import <path>
• 用户说“img2img／使用这张图片” → 先执行 comfyui-skill --json upload <image>，再执行工作流
• 用户说“局部重绘／遮罩这个区域” → 执行 comfyui-skill --json upload <mask> --mask，再执行工作流
• 用户说“显示之前的结果” → comfyui-skill --json history list <id>
• 用户说“哪里失败了／检查任务状态” → comfyui-skill --json jobs list --status failed
• 用户说“哪个服务的显存更多” → comfyui-skill --json server stats --all
• 用户说“有哪些可用节点” → 使用 MCP nodes 实时发现生态中的节点；仅需 CLI 节点清单时，使用 comfyui-skill --json nodes list。
• 用户说“试运行／不执行测试” → comfyui-skill --json run <id> --validate
• 用户说“打开管理界面” → python3 ./ui/open_ui.py

核心概念

• 技能 ID：<server_id>/<workflow_id>（例如，local/txt2img）。如果省略服务，则使用默认服务。
• 架构：每个工作流都有一个 schema.json，用于将业务参数名称（例如，prompt、seed）映射到 ComfyUI 内部节点字段。绝不要向用户透露节点 ID。
• 服务：在 config.json 中配置的一个或多个 ComfyUI 实例。使用 server status 检查运行状况。
• 两个接口，一个技能：CLI 是已知工作流的高效执行路径。官方 MCP 是发现和编排当前 ComfyUI 生态的自适应路径。两者服务于同一业务意图，不得重复提交同一个任务。

官方本地 Comfy MCP

当 Agent 宿主提供官方 Comfy MCP 工具时，请直接调用这些工具。每次 MCP 流程都从 server_info 开始，并使用实时工具架构，不要假设参数或工具可用性。

当宿主未提供 MCP 工具，但可以运行 shell 命令时，请使用附带的 stdio 桥接程序：

python ./scripts/comfy_mcp.py probe
python ./scripts/comfy_mcp.py tools
python ./scripts/comfy_mcp.py call search_templates --arguments '{"query":"background removal"}'

桥接程序会从 config.json 中选定的服务读取 mcp_command、mcp_args、mcp_python、mcp_cwd 和 mcp_env。probe 和 tools 只读。call 会产生相应官方工具的副作用。

当请求涉及 MCP 发现、原始工作流验证、模板适配、作业管理、安装、生命周期控制或合作伙伴模型时，请阅读 references/comfy-mcp.md。

路由原则：

• 对于已知的 <server_id>/<workflow_id>，优先使用 CLI；MCP 并非必经步骤。
• 如果答案取决于当前已安装的模板、节点、模型、硬件或官方工具约定，则优先使用 MCP。
• 对于较长的 MCP 运行：run_workflow(wait=false) 或 run_template(wait=false) -> job(action="wait"|"status") -> fetch_outputs。
• 任一路径返回 prompt_id 后，都应继续通过该路径轮询。绝不要通过重新提交来回退。
• 未获得用户对该付费调用的明确批准时，绝不要设置 confirm_spend=true。

命令参考

命令	用途
comfyui-skill --json server status	检查 ComfyUI 服务是否在线
comfyui-skill --json server stats	显示 VRAM、RAM、GPU、版本（多服务时使用 --all）
comfyui-skill --json list	列出所有可用工作流及其参数
comfyui-skill --json info <id>	显示工作流详情和参数架构
comfyui-skill --json submit <id> --args '{...}'	提交工作流（非阻塞）
comfyui-skill --json status <prompt_id>	检查执行状态
comfyui-skill --json run <id> --args '{...}'	执行工作流（阻塞，实时流式传输）
comfyui-skill --json run <id> --validate	验证工作流，不执行
comfyui-skill --json upload <path>	将图像上传到 ComfyUI（用于 img2img 工作流）
comfyui-skill --json upload <path> --mask	上传遮罩图像（用于修复工作流）
comfyui-skill --json nodes list	列出所有可用的 ComfyUI 节点
comfyui-skill --json jobs list	列出服务端作业历史记录（使用 --status failed 筛选）
comfyui-skill --json deps check <id>	检查缺失的依赖项
comfyui-skill --json deps install <id> --repos '[...]'	安装缺失的自定义节点
comfyui-skill --json workflow import <path>	导入工作流（自动检测，并警告已弃用的节点）
comfyui-skill --json history list <id>	列出工作流的执行历史

---

执行流程

第 1 步：查询可用工作流

comfyui-skill --json list

返回包含所有已启用工作流及其参数的 JSON 数组。

• required: true 参数 → 如果用户未提供，请询问用户。
• required: false 参数 → 根据上下文推断（例如，seed = 随机数），或省略。
• 绝不要暴露节点 ID；只使用业务参数名称（例如，prompt、style）。
• 如果匹配多个工作流，请选择最相关的一个，或列出候选项。

第 2 步：组装参数

将参数组装成 JSON 字符串。示例：

{"prompt": "A beautiful landscape, high quality, masterpiece", "seed": 40128491}

如果缺少关键参数，请询问用户（例如：“您希望采用什么视觉风格？”）。

步骤 3：执行前依赖检查

首次执行工作流前，务必运行：

comfyui-skill --json deps check <server_id>/<workflow_id>

• 如果 is_ready 为 true → 继续执行步骤 4。
• 如果 is_ready 为 false：
  1. 向用户列出缺少的节点和模型。
  2. 如果用户同意安装，运行：

     comfyui-skill --json deps install <id> --repos '["https://github.com/repo1"]'
     

     使用检查报告中的 source_repo URL 作为 --repos 的值。
  3. 如果 needs_restart 为 true，告知用户重启 ComfyUI，然后重新检查。
  4. 缺少的模型必须手动下载——告知用户应将其放入哪个文件夹（例如 checkpoints）。

步骤 4：执行工作流

注意：JSON 参数必须用单引号括起来，以防 bash 解析双引号。

根据你的环境选择执行模式：

交互模式：submit + status（推荐用于聊天）

步骤 4a — 提交：

comfyui-skill --json submit <id> --args '{"prompt": "..."}'

返回：{"status": "submitted", "prompt_id": "..."}。告知用户生成已开始。

步骤 4b — 轮询：

comfyui-skill --json status <prompt_id>

状态值：queued（包含 position）→ running → success（包含 outputs）或 error。

轮询模式——实时反馈至关重要：

每次 status 调用都必须是单独的工具调用（单独的 bash 命令）。不要编写 shell 循环。正确的模式如下：

1. 将 status 作为独立的 bash 命令运行。
2. 读取返回的 JSON。
3. 如果状态为 queued 或 running：向用户发送进度文本，然后再次运行 status。
4. 如果状态为 success：继续执行步骤 5。
5. 如果状态为 error：报告错误。

非交互模式：一次性阻塞执行（适用于脚本/CI）

comfyui-skill --json run <id> --args '{"prompt": "..."}'

阻塞等待直至完成。返回与 status 相同格式且状态为 success 的结果。

步骤 5：展示结果

成功时，结果包含一个 outputs 数组，其中包含文件引用（filename、subfolder、type）。 使用你自身的功能向用户展示文件（例如，图片预览、文件路径）。

---

工作流导入

用户想要添加新工作流（而非执行现有工作流）时：

comfyui-skill --json workflow import <json_path>

• 同时支持 API 格式和编辑器格式（自动检测并自动转换）。
• 自动生成 schema.json，并智能提取参数。
• 导入后，在首次执行前检查依赖。

如需从 ComfyUI 服务或本地文件夹批量导入，请参阅 references/workflow-import.md。

故障排除

1. ComfyUI 离线：运行 comfyui-skill --json server status。如果处于离线状态，请让用户启动 ComfyUI。
2. 未找到工作流：运行 comfyui-skill --json list 查看可用工作流。如果缺少该工作流，用户需要先导入。
3. 参数格式错误：确保 --args 是用单引号括起来的有效 JSON。
4. 云节点未经授权：工作流使用了云 API 节点（Kling、Sora 等）。引导用户：(1) 在 https://platform.comfy.org 生成 API Key；(2) 打开 Web UI → Server Settings → 填写“ComfyUI API Key”。