The local manager API also exposes higher-level workflow execution and history routes:

• POST /api/servers/{server_id}/workflow/{workflow_id}/run
• GET /api/servers/{server_id}/workflow/{workflow_id}/history
• GET /api/servers/{server_id}/workflow/{workflow_id}/history/{run_id}

Server Health Check

Before running a workflow, check whether the target ComfyUI server is online.

You can query the manager API endpoint:

GET /api/servers/{server_id}/status

This returns JSON with "status": "online" or "status": "offline".

Recommended agent flow: Before Step 3 (Trigger Image Generation), run a server status check. If offline, ask the user to start ComfyUI and retry once it is online.

Step 0: Workflow Onboarding and Import (Optional)

Use the manager UI/API when the user wants to register workflows into this skill instead of running them immediately.

• For bulk import from ComfyUI /userdata, local files, manager API routes, and import result semantics, read references/workflow-import.md.
• Prefer the bulk import flow when the user wants to sync many saved workflows at once.
• Use single-workflow configuration only when the user gives one workflow and wants a targeted setup.

Single-workflow auto-configuration

If the user provides you with one new ComfyUI workflow JSON (API format) and asks you to "configure it" or "add it":

1. Check the existing server configurations or default to local.
2. Save the provided JSON file to ./data/<server_id>/<new_workflow_id>/workflow.json.
3. Analyze the JSON structure (look for inputs inside node definitions, e.g., KSampler's seed, CLIPTextEncode's text for positive/negative prompts, EmptyLatentImage for width/height).
4. Automatically generate a schema mapping file and save it to ./data/<server_id>/<new_workflow_id>/schema.json. The schema format must follow:

   {
     "workflow_id": "<new_workflow_id>",
     "server_id": "<server_id>",
     "description": "Auto-configured by OpenClaw",
     "enabled": true,
     "parameters": {
       "prompt": { "node_id": "3", "field": "text", "required": true, "type": "string", "description": "Positive prompt" }
       // Add other sensible parameters that the user might want to tweak
     }
   }
   

5. Tell the user that the new workflow on the specific server is successfully configured and ready to be used.

Step 1: Query Available Workflows (Registry)

Before attempting to generate any image, you must first query the registry to understand which workflows are currently supported and enabled:

python ./scripts/registry.py list --agent

Return Format Parsing: You will receive a JSON containing all available workflows. Notice they are uniquely identified by the combination of server_id and workflow_id (or path format <server_id>/<workflow_id>):

• For parameters with required: true, if the user hasn't provided them, you must ask the user to provide them.
• For parameters with required: false, you can infer and generate them yourself based on the user's description (e.g., translating and optimizing the user's scene), or simply use empty values/random numbers (e.g., seed = random number).
• Never expose underlying node information to the user (do not mention Node IDs); only ask about business parameter names (e.g., prompt, style).
• If multiple workflows match the user prompt across different servers, you may list them acting as candidates, OR simply pick the most relevant one and execute it directly to provide the best user experience.

Step 2: Parameter Assembly and Interaction

Once you have identified the workflow to use and collected/generated all necessary parameters, you need to assemble them into a compact JSON string. For example, if the schema exposes prompt and seed, you need to construct: {"prompt": "A beautiful landscape, high quality, masterpiece", "seed": 40128491}

If critical parameters are missing, politely ask the user using notify_user. For example: "To generate the image you need, would you like a specific person or animal? Do you have an expected visual style?"

Step 3: Trigger the Image Generation Task

Once the complete parameters are collected, execute the workflow client in a command-line environment (ensure your current working directory is the project root, or navigate to it first).

Pass the full identifier as <server_id>/<workflow_id>.

Note: Outer curly braces must be wrapped in single quotes to prevent bash from incorrectly parsing JSON double quotes.

python ./scripts/comfyui_client.py --workflow <server_id>/<workflow_id> --args '{"key1": "value1", "key2": 123}'

Blocking and Result Retrieval:

• This script will automatically submit the task to the matched server and poll to wait for ComfyUI to finish rendering, then download the image locally.
• If executed successfully, the standard output of the script will provide a JSON containing run_id, prompt_id, and an images list whose values are absolute local file paths.
• If execution fails after a history record is created, the JSON may still include run_id together with error, which can be used to inspect the saved execution record through the manager UI/API.
• Under the hood, this flow uses the native ComfyUI route sequence POST /prompt -> GET /history/{prompt_id} -> GET /view.

The manager stores execution history per workflow, including raw args, resolved args, prompt ID, result files, status, timing, and error summary. History records live under data/<server_id>/<workflow_id>/history/.

Step 4: Send the Image to the User

Once you obtain the absolute local path to the generated image, use your native capabilities to present the file to the user (e.g., in an OpenClaw environment, returning the path allows the client to intercept it and convert it into rich text or an image preview).

Common Troubleshooting & Notices

1. ComfyUI Offline: If the script returns "Error connecting to ComfyUI", run a server status check and ask the user to start the ComfyUI service for that server URL before retrying.
2. Schema Not Found: If you directly called a workflow the user mentioned verbally, but the script reports a missing Schema, perform Step 1 registry.py and tell the user they need to first go to the Web UI panel to upload and configure the mapping for that workflow on the desired server.
3. Parameter Format Error: Ensure that the JSON passed via --args is a valid JSON string wrapped in single quotes.

Web UI

• Frontend source lives in a separate repository; run scripts/update_frontend.sh to pull the latest build
• Runtime update checks prefer pulling the main repo via git, and fall back to refreshing ui/static/ from the frontend release when git update is unavailable
• A local web interface for managing all servers and workflows in one place
• Reorder workflows by dragging, or sort by name, status, or custom order
• Search and filter workflows across all servers
• Available in English, Simplified Chinese, and Traditional Chinese — switch languages from the UI

Configuration Transfer

• Export your current configuration and workflows into a single portable JSON file
• Choose exactly which workflows to include before exporting
• Preview what will change on the target machine before applying an import
• Control whether to overwrite existing workflows or sync environment settings from the source machine

Workflow Execution

• Submit a job, wait for it to finish, and download the generated images to local storage automatically
• Supports multi-image output in a single run
• Agents ...