comfyui-skill-openclaw

ComfyUI エージェント SKILL

前提条件：CLI をインストールしてください：pip install -U comfyui-skill-cli。公式ローカル Comfy MCP は任意です。MCP の機能が必要な場合は、公式ガイドに従って接続してください。すべてのシェルコマンドは、このプロジェクトのルートディレクトリ（この 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
• ユーザーが「どのサーバーの VRAM が多い？」と言った場合 → comfyui-skill --json server stats --all
• ユーザーが「利用可能なノードは？」と言った場合 → エコシステムの最新情報を確認するには MCP の nodes を使用します。CLI の一覧だけが必要な場合は comfyui-skill --json nodes list を使用します。
• ユーザーが「ドライラン／実行せずにテストして」と言った場合 → comfyui-skill --json run <id> --validate
• ユーザーが「管理 UI を開いて」と言った場合 → python3 ./ui/open_ui.py

主な概念

• スキル ID：<server_id>/<workflow_id>（例：local/txt2img）。サーバーが省略された場合は、既定のサーバーが使用されます。
• スキーマ：各ワークフローには、業務パラメーター名（例：prompt、seed）を内部の ComfyUI ノードフィールドに対応付ける schema.json があります。ノード ID をユーザーに見せてはいけません。
• サーバー：config.json で設定された 1 つ以上の ComfyUI インスタンスです。server status で正常性を確認してください。
• 2 つのインターフェース、1 つのスキル：既知のワークフローを効率よく実行するには CLI を使用します。現在の ComfyUI エコシステムを探索して連携するには、公式 MCP を使用します。両者は同じ目的を共有しており、同じジョブを二重に送信してはいけません。

公式ローカル Comfy MCP

エージェントホストから公式 Comfy MCP ツールを利用できる場合は、それらのツールを直接呼び出してください。すべての MCP フローを server_info から開始し、パラメーターや利用可能なツールを推測せず、最新のツールスキーマを使用してください。

ホストから MCP ツールを利用できないものの、シェルコマンドを実行できる場合は、付属の 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 の検出、raw-workflow の検証、テンプレートの適応、ジョブ管理、インストール、ライフサイクル制御、またはパートナーモデルが必要な場合は、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 は決して公開せず、プロンプトやスタイルなどの業務用パラメーター名だけを使用してください。
• 複数のワークフローが一致する場合は、最も関連性の高いものを選ぶか、候補を列挙してください。

ステップ 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：ワークフローを実行する

注：bash が二重引用符を解析しないように、JSON 引数は一重引用符で囲む必要があります。

環境に応じて実行モードを選択します：

インタラクティブモード：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 コマンド）にする必要があります。シェルループは書かないでください。正しい手順は次のとおりです：

1. status を単独の bash コマンドとして実行します。
2. 返された JSON を読み取ります。
3. queued または running の場合：進捗状況をテキストメッセージでユーザーに送信してから、もう一度 status を実行します。
4. success の場合：ステップ 5 に進みます。
5. error の場合：エラーを報告します。

非インタラクティブモード：一度だけ実行して完了まで待機（スクリプト／CI 向け）

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

完了するまでブロックします。success の status と同じ形式の結果を返します。

ステップ 5：結果を提示する

成功すると、結果にはファイル参照（filename、subfolder、type）を含む outputs 配列が含まれます。 ネイティブ機能を使って、ファイルをユーザーに提示します（例：画像プレビュー、ファイルパス）。

---

ワークフローのインポート

ユーザーが新しいワークフローを追加する場合（既存のものを実行するのではなく）：

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」に入力する。