@openclaw/comfy-provider 0.0.0 → 2026.8.1-beta.2

package/README.md

@@ -1,3 +1,26 @@
 # @openclaw/comfy-provider
 
-Reserved placeholder for the official OpenClaw plugin package. Use a published release version instead.
+Official ComfyUI image, video, and music generation provider plugin for
+OpenClaw.
+
+## Install
+
+```bash
+openclaw plugins install @openclaw/comfy-provider
+openclaw gateway restart
+```
+
+## Configure
+
+Local ComfyUI workflows do not require credentials. Comfy Cloud workflows use
+`COMFY_API_KEY` or `COMFY_CLOUD_API_KEY`.
+
+Full workflow, model, and provider configuration:
+
+- https://docs.openclaw.ai/providers/comfy
+
+## Package
+
+- Plugin id: `comfy`
+- Package: `@openclaw/comfy-provider`
+- Minimum OpenClaw host: `2026.7.2`

package/dist/image-generation-provider.js

@@ -0,0 +1,63 @@
+import { DEFAULT_COMFY_MODEL, isComfyCapabilityConfigured, runComfyWorkflow } from "./workflow-runtime.js";
+//#region extensions/comfy/image-generation-provider.ts
+function buildComfyImageGenerationProvider() {
+	return {
+		id: "comfy",
+		label: "ComfyUI",
+		defaultModel: DEFAULT_COMFY_MODEL,
+		models: [DEFAULT_COMFY_MODEL],
+		isConfigured: ({ cfg, agentDir }) => isComfyCapabilityConfigured({
+			cfg,
+			agentDir,
+			capability: "image"
+		}),
+		capabilities: {
+			generate: {
+				maxCount: 1,
+				supportsSize: false,
+				supportsAspectRatio: false,
+				supportsResolution: false
+			},
+			edit: {
+				enabled: true,
+				maxCount: 1,
+				maxInputImages: 1,
+				supportsSize: false,
+				supportsAspectRatio: false,
+				supportsResolution: false
+			}
+		},
+		async generateImage(req) {
+			if ((req.inputImages?.length ?? 0) > 1) throw new Error("Comfy image generation currently supports at most one reference image");
+			const result = await runComfyWorkflow({
+				cfg: req.cfg,
+				agentDir: req.agentDir,
+				authStore: req.authStore,
+				prompt: req.prompt,
+				model: req.model,
+				timeoutMs: req.timeoutMs,
+				capability: "image",
+				outputKinds: ["images"],
+				inputImage: req.inputImages?.[0]
+			});
+			return {
+				images: result.assets.map((asset) => ({
+					buffer: asset.buffer,
+					mimeType: asset.mimeType,
+					fileName: asset.fileName,
+					metadata: {
+						nodeId: asset.nodeId,
+						promptId: result.promptId
+					}
+				})),
+				model: result.model,
+				metadata: {
+					promptId: result.promptId,
+					outputNodeIds: result.outputNodeIds
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { buildComfyImageGenerationProvider };

package/dist/index.js

@@ -0,0 +1,44 @@
+import { buildComfyImageGenerationProvider } from "./image-generation-provider.js";
+import { buildComfyMusicGenerationProvider } from "./music-generation-provider.js";
+import { buildComfyVideoGenerationProvider } from "./video-generation-provider.js";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { createProviderApiKeyAuthMethod } from "openclaw/plugin-sdk/provider-auth-api-key";
+//#region extensions/comfy/index.ts
+const PROVIDER_ID = "comfy";
+var comfy_default = definePluginEntry({
+	id: PROVIDER_ID,
+	name: "ComfyUI Provider",
+	description: "Bundled ComfyUI workflow media generation provider",
+	register(api) {
+		api.registerProvider({
+			id: PROVIDER_ID,
+			label: "ComfyUI",
+			docsPath: "/providers/comfy",
+			envVars: ["COMFY_API_KEY", "COMFY_CLOUD_API_KEY"],
+			auth: [createProviderApiKeyAuthMethod({
+				providerId: PROVIDER_ID,
+				methodId: "cloud-api-key",
+				label: "Comfy Cloud API key",
+				hint: "API key for Comfy Cloud workflow runs",
+				optionKey: "comfyApiKey",
+				flagName: "--comfy-api-key",
+				envVar: "COMFY_API_KEY",
+				promptMessage: "Enter Comfy Cloud API key",
+				wizard: {
+					choiceId: "comfy-cloud-api-key",
+					choiceLabel: "Comfy Cloud API key",
+					choiceHint: "Required for cloud workflows",
+					groupId: "comfy",
+					groupLabel: "ComfyUI",
+					groupHint: "Local or cloud workflows",
+					onboardingScopes: ["image-generation"]
+				}
+			})]
+		});
+		api.registerImageGenerationProvider(buildComfyImageGenerationProvider());
+		api.registerMusicGenerationProvider(buildComfyMusicGenerationProvider());
+		api.registerVideoGenerationProvider(buildComfyVideoGenerationProvider());
+	}
+});
+//#endregion
+export { comfy_default as default };

package/dist/music-generation-provider.js

@@ -0,0 +1,63 @@
+import { DEFAULT_COMFY_MODEL, isComfyCapabilityConfigured, runComfyWorkflow } from "./workflow-runtime.js";
+//#region extensions/comfy/music-generation-provider.ts
+const COMFY_MAX_INPUT_IMAGES = 1;
+function toGeneratedTrack(asset) {
+	return {
+		buffer: asset.buffer,
+		mimeType: asset.mimeType,
+		fileName: asset.fileName
+	};
+}
+function resolveInputImage(inputImage) {
+	if (!inputImage) return;
+	if (!inputImage.buffer) throw new Error("Comfy music generation requires loaded reference image bytes.");
+	return {
+		buffer: inputImage.buffer,
+		mimeType: inputImage.mimeType ?? "image/png",
+		fileName: inputImage.fileName
+	};
+}
+function buildComfyMusicGenerationProvider() {
+	return {
+		id: "comfy",
+		label: "ComfyUI",
+		defaultModel: DEFAULT_COMFY_MODEL,
+		models: [DEFAULT_COMFY_MODEL],
+		isConfigured: ({ cfg, agentDir }) => isComfyCapabilityConfigured({
+			cfg,
+			agentDir,
+			capability: "music"
+		}),
+		capabilities: {
+			generate: {},
+			edit: {
+				enabled: true,
+				maxInputImages: COMFY_MAX_INPUT_IMAGES
+			}
+		},
+		async generateMusic(req) {
+			if ((req.inputImages?.length ?? 0) > COMFY_MAX_INPUT_IMAGES) throw new Error(`Comfy music generation supports at most ${COMFY_MAX_INPUT_IMAGES} reference image.`);
+			const result = await runComfyWorkflow({
+				cfg: req.cfg,
+				agentDir: req.agentDir,
+				authStore: req.authStore,
+				prompt: req.prompt,
+				model: req.model,
+				capability: "music",
+				outputKinds: ["audio"],
+				inputImage: resolveInputImage(req.inputImages?.[0])
+			});
+			return {
+				tracks: result.assets.map(toGeneratedTrack),
+				model: result.model,
+				metadata: {
+					promptId: result.promptId,
+					outputNodeIds: result.outputNodeIds,
+					inputImageCount: req.inputImages?.length ?? 0
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { buildComfyMusicGenerationProvider };

package/dist/video-generation-provider.js

@@ -0,0 +1,82 @@
+import { DEFAULT_COMFY_MODEL, isComfyCapabilityConfigured, runComfyWorkflow } from "./workflow-runtime.js";
+//#region extensions/comfy/video-generation-provider.ts
+function toComfyInputImage(inputImage) {
+	if (!inputImage) return;
+	if (!inputImage.buffer || !inputImage.mimeType) throw new Error("Comfy video generation requires a local reference image file");
+	return {
+		buffer: inputImage.buffer,
+		mimeType: inputImage.mimeType,
+		fileName: inputImage.fileName
+	};
+}
+function buildComfyVideoGenerationProvider() {
+	return {
+		id: "comfy",
+		label: "ComfyUI",
+		defaultModel: DEFAULT_COMFY_MODEL,
+		models: [DEFAULT_COMFY_MODEL],
+		isConfigured: ({ cfg, agentDir }) => isComfyCapabilityConfigured({
+			cfg,
+			agentDir,
+			capability: "video"
+		}),
+		capabilities: {
+			generate: {
+				maxVideos: 1,
+				supportsSize: false,
+				supportsAspectRatio: false,
+				supportsResolution: false,
+				supportsAudio: false,
+				supportsWatermark: false
+			},
+			imageToVideo: {
+				enabled: true,
+				maxVideos: 1,
+				maxInputImages: 1,
+				supportsSize: false,
+				supportsAspectRatio: false,
+				supportsResolution: false,
+				supportsAudio: false,
+				supportsWatermark: false
+			},
+			videoToVideo: { enabled: false }
+		},
+		async generateVideo(req) {
+			if ((req.inputImages?.length ?? 0) > 1) throw new Error("Comfy video generation currently supports at most one reference image");
+			if ((req.inputVideos?.length ?? 0) > 0) throw new Error("Comfy video generation does not support input videos");
+			const result = await runComfyWorkflow({
+				cfg: req.cfg,
+				agentDir: req.agentDir,
+				authStore: req.authStore,
+				prompt: req.prompt,
+				model: req.model,
+				timeoutMs: req.timeoutMs,
+				capability: "video",
+				outputKinds: [
+					"images",
+					"gifs",
+					"videos"
+				],
+				inputImage: toComfyInputImage(req.inputImages?.[0])
+			});
+			return {
+				videos: result.assets.map((asset) => ({
+					buffer: asset.buffer,
+					mimeType: asset.mimeType,
+					fileName: asset.fileName,
+					metadata: {
+						nodeId: asset.nodeId,
+						promptId: result.promptId
+					}
+				})),
+				model: result.model,
+				metadata: {
+					promptId: result.promptId,
+					outputNodeIds: result.outputNodeIds
+				}
+			};
+		}
+	};
+}
+//#endregion
+export { buildComfyVideoGenerationProvider };

package/dist/workflow-runtime.js

@@ -0,0 +1,480 @@
+import fs from "node:fs/promises";
+import { canResolveEnvSecretRefInReadOnlyPath } from "openclaw/plugin-sdk/extension-shared";
+import { resolveGeneratedMediaMaxBytes } from "openclaw/plugin-sdk/media-generation-runtime";
+import { extensionForMime } from "openclaw/plugin-sdk/media-mime";
+import { resolvePositiveTimerTimeoutMs } from "openclaw/plugin-sdk/number-runtime";
+import { isProviderApiKeyConfigured } from "openclaw/plugin-sdk/provider-auth";
+import { resolveApiKeyForProvider } from "openclaw/plugin-sdk/provider-auth-runtime";
+import { assertOkOrThrowHttpError, normalizeBaseUrl, readProviderJsonResponse, resolveProviderHttpRequestConfig } from "openclaw/plugin-sdk/provider-http";
+import { readResponseWithLimit } from "openclaw/plugin-sdk/response-limit-runtime";
+import { normalizeSecretInputString, resolveSecretInputString } from "openclaw/plugin-sdk/secret-input-runtime";
+import { fetchWithSsrFGuard, isPrivateOrLoopbackHost, mergeSsrFPolicies, ssrfPolicyFromHttpBaseUrlAllowedOrigin } from "openclaw/plugin-sdk/ssrf-runtime";
+import { asBoolean, isRecord, normalizeOptionalLowercaseString, normalizeOptionalString, uniqueStrings } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { resolveUserPath } from "openclaw/plugin-sdk/text-utility-runtime";
+//#region extensions/comfy/workflow-runtime.ts
+const DEFAULT_COMFY_LOCAL_BASE_URL = "http://127.0.0.1:8188";
+const DEFAULT_COMFY_CLOUD_BASE_URL = "https://cloud.comfy.org";
+const DEFAULT_PROMPT_INPUT_NAME = "text";
+const DEFAULT_INPUT_IMAGE_INPUT_NAME = "image";
+const DEFAULT_POLL_INTERVAL_MS = 1500;
+const DEFAULT_TIMEOUT_MS = 5 * 6e4;
+const DEFAULT_COMFY_MODEL = "workflow";
+function readConfigInteger(config, key) {
+	const value = config[key];
+	return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : void 0;
+}
+function getComfyConfig(cfg) {
+	const pluginConfig = cfg?.plugins?.entries?.comfy?.config;
+	if (isRecord(pluginConfig)) return pluginConfig;
+	const legacyConfig = cfg?.models?.providers?.comfy;
+	return isRecord(legacyConfig) ? legacyConfig : {};
+}
+function stripNestedCapabilityConfig(config) {
+	const next = { ...config };
+	delete next.image;
+	delete next.video;
+	delete next.music;
+	return next;
+}
+function getComfyCapabilityConfig(config, capability) {
+	const shared = stripNestedCapabilityConfig(config);
+	const nested = config[capability];
+	if (!isRecord(nested)) return shared;
+	return {
+		...shared,
+		...nested
+	};
+}
+function resolveComfyMode(config) {
+	return normalizeOptionalString(config.mode) === "cloud" ? "cloud" : "local";
+}
+function resolveComfyApiKey(config, cfg) {
+	const resolved = resolveSecretInputString({
+		value: config.apiKey,
+		path: "plugins.entries.comfy.config.apiKey",
+		defaults: cfg?.secrets?.defaults,
+		mode: "inspect"
+	});
+	if (resolved.status === "available") {
+		const apiKey = normalizeSecretInputString(resolved.value);
+		return apiKey ? {
+			status: "available",
+			apiKey,
+			source: "plugins.entries.comfy.config.apiKey"
+		} : { status: "missing" };
+	}
+	if (resolved.status === "configured_unavailable") {
+		if (resolved.ref.source !== "env") return { status: "configured_unavailable" };
+		const envVarName = resolved.ref.id.trim();
+		if (!canResolveEnvSecretRefInReadOnlyPath({
+			cfg,
+			provider: resolved.ref.provider,
+			id: envVarName
+		})) return { status: "configured_unavailable" };
+		const apiKey = normalizeSecretInputString(process.env[envVarName]);
+		return apiKey ? {
+			status: "available",
+			apiKey,
+			source: `plugins.entries.comfy.config.apiKey (${envVarName})`
+		} : { status: "configured_unavailable" };
+	}
+	return { status: "missing" };
+}
+function getRequiredConfigString(config, key) {
+	const value = normalizeOptionalString(config[key]);
+	if (!value) throw new Error(`plugins.entries.comfy.config.${key} is required`);
+	return value;
+}
+function resolveComfyWorkflowSource(config) {
+	const workflow = config.workflow;
+	if (isRecord(workflow)) return { workflow: structuredClone(workflow) };
+	return { workflowPath: normalizeOptionalString(config.workflowPath) };
+}
+async function loadComfyWorkflow(config) {
+	const source = resolveComfyWorkflowSource(config);
+	if (source.workflow) return source.workflow;
+	if (!source.workflowPath) throw new Error("plugins.entries.comfy.config.<capability>.workflow or workflowPath is required");
+	const resolvedPath = resolveUserPath(source.workflowPath);
+	const raw = await fs.readFile(resolvedPath, "utf8");
+	const parsed = JSON.parse(raw);
+	if (!isRecord(parsed)) throw new Error(`Comfy workflow at ${resolvedPath} must be a JSON object`);
+	return parsed;
+}
+function setWorkflowInput(params) {
+	const node = params.workflow[params.nodeId];
+	if (!isRecord(node)) throw new Error(`Comfy workflow missing node "${params.nodeId}"`);
+	const inputs = node.inputs;
+	if (!isRecord(inputs)) throw new Error(`Comfy workflow node "${params.nodeId}" is missing an inputs object`);
+	inputs[params.inputName] = params.value;
+}
+function resolveComfyNetworkPolicy(params) {
+	let parsed;
+	try {
+		parsed = new URL(params.baseUrl);
+	} catch {
+		return {};
+	}
+	const hostname = normalizeOptionalLowercaseString(parsed.hostname) ?? "";
+	if (!hostname) return {};
+	const localHostnamePolicy = params.mode === "local" ? { hostnameAllowlist: [hostname] } : void 0;
+	const hostnameOnlyPolicy = localHostnamePolicy ? { apiPolicy: localHostnamePolicy } : {};
+	if (!params.allowPrivateNetwork) return hostnameOnlyPolicy;
+	if (!params.explicitAllowPrivateNetwork && params.mode !== "local") return {};
+	if (!params.explicitAllowPrivateNetwork && params.mode === "local" && !isPrivateOrLoopbackHost(hostname) && !isSingleLabelServiceHostname(hostname)) return hostnameOnlyPolicy;
+	const originPolicy = ssrfPolicyFromHttpBaseUrlAllowedOrigin(params.baseUrl);
+	if (!originPolicy) return hostnameOnlyPolicy;
+	return { apiPolicy: params.mode === "local" ? mergeSsrFPolicies(originPolicy, localHostnamePolicy) : originPolicy };
+}
+function isSingleLabelServiceHostname(hostname) {
+	return /^[a-z0-9_](?:[a-z0-9_-]{0,61}[a-z0-9_])?$/u.test(hostname);
+}
+async function readJsonResponse(params) {
+	const { response, release } = await fetchWithSsrFGuard({
+		url: params.url,
+		init: params.init,
+		timeoutMs: params.timeoutMs,
+		policy: params.policy,
+		dispatcherPolicy: params.dispatcherPolicy,
+		auditContext: params.auditContext
+	});
+	try {
+		await assertOkOrThrowHttpError(response, params.errorPrefix);
+		return await readProviderJsonResponse(response, params.errorPrefix);
+	} finally {
+		await release();
+	}
+}
+function resolveFileExtension(params) {
+	const extension = extensionForMime(params.mimeType);
+	if (extension) return extension.slice(1);
+	const fileName = params.fileName?.trim();
+	if (!fileName) return "bin";
+	const dotIndex = fileName.lastIndexOf(".");
+	if (dotIndex < 0 || dotIndex === fileName.length - 1) return "bin";
+	return fileName.slice(dotIndex + 1);
+}
+function toBlobBytes(buffer) {
+	const arrayBuffer = new ArrayBuffer(buffer.byteLength);
+	new Uint8Array(arrayBuffer).set(buffer);
+	return arrayBuffer;
+}
+async function uploadInputImage(params) {
+	const form = new FormData();
+	form.set("image", new Blob([toBlobBytes(params.image.buffer)], { type: params.image.mimeType }), normalizeOptionalString(params.image.fileName) || `input.${resolveFileExtension({ mimeType: params.image.mimeType })}`);
+	form.set("type", "input");
+	form.set("overwrite", "true");
+	const headers = new Headers(params.headers);
+	headers.delete("Content-Type");
+	const payload = await readJsonResponse({
+		url: `${params.baseUrl}${params.mode === "cloud" ? "/api/upload/image" : "/upload/image"}`,
+		init: {
+			method: "POST",
+			headers,
+			body: form
+		},
+		timeoutMs: params.timeoutMs,
+		policy: params.policy,
+		dispatcherPolicy: params.dispatcherPolicy,
+		auditContext: `comfy-${params.capability}-upload`,
+		errorPrefix: "Comfy image upload failed"
+	});
+	const uploadedName = normalizeOptionalString(payload.filename) || normalizeOptionalString(payload.name);
+	if (!uploadedName) throw new Error("Comfy image upload response missing filename");
+	return uploadedName;
+}
+function extractHistoryEntry(history, promptId) {
+	if (!isRecord(history)) return null;
+	const directOutputs = history.outputs;
+	if (isRecord(directOutputs)) return history;
+	const nested = history[promptId];
+	if (isRecord(nested)) return nested;
+	return null;
+}
+async function waitForLocalHistory(params) {
+	const deadline = Date.now() + params.timeoutMs;
+	for (;;) {
+		const requestTimeoutMs = resolveComfyRemainingMs(deadline, params.timeoutMs);
+		const entry = extractHistoryEntry(await readJsonResponse({
+			url: `${params.baseUrl}/history/${params.promptId}`,
+			init: {
+				method: "GET",
+				headers: params.headers
+			},
+			timeoutMs: requestTimeoutMs,
+			policy: params.policy,
+			dispatcherPolicy: params.dispatcherPolicy,
+			auditContext: "comfy-history",
+			errorPrefix: "Comfy history lookup failed"
+		}), params.promptId);
+		if (entry?.outputs && Object.keys(entry.outputs).length > 0) return entry;
+		const pollDelayMs = resolveComfyRemainingMs(deadline, params.timeoutMs, params.pollIntervalMs);
+		await new Promise((resolve) => {
+			setTimeout(resolve, pollDelayMs);
+		});
+	}
+}
+async function waitForCloudCompletion(params) {
+	const deadline = Date.now() + params.timeoutMs;
+	for (;;) {
+		const requestTimeoutMs = resolveComfyRemainingMs(deadline, params.timeoutMs);
+		const status = await readJsonResponse({
+			url: `${params.baseUrl}/api/job/${params.promptId}/status`,
+			init: {
+				method: "GET",
+				headers: params.headers
+			},
+			timeoutMs: requestTimeoutMs,
+			policy: params.policy,
+			dispatcherPolicy: params.dispatcherPolicy,
+			auditContext: "comfy-status",
+			errorPrefix: "Comfy status lookup failed"
+		});
+		if (status.status === "completed") return;
+		if (status.status === "failed" || status.status === "cancelled") throw new Error(`Comfy workflow ${status.status}: ${status.error ?? status.message ?? params.promptId}`);
+		const pollDelayMs = resolveComfyRemainingMs(deadline, params.timeoutMs, params.pollIntervalMs);
+		await new Promise((resolve) => {
+			setTimeout(resolve, pollDelayMs);
+		});
+	}
+}
+function resolveComfyRemainingMs(deadline, timeoutMs, defaultTimeoutMs = timeoutMs) {
+	const defaultMs = resolvePositiveTimerTimeoutMs(defaultTimeoutMs, 1);
+	const remainingMs = deadline - Date.now();
+	if (remainingMs <= 0) throw new Error(`Comfy workflow did not finish within ${Math.ceil(timeoutMs / 1e3)}s`);
+	return Math.max(1, Math.min(defaultMs, remainingMs));
+}
+function collectOutputFiles(params) {
+	const outputs = params.history.outputs;
+	if (!outputs) return [];
+	const nodeIds = params.outputNodeId ? [params.outputNodeId] : Object.keys(outputs);
+	const files = [];
+	for (const nodeId of nodeIds) {
+		const entry = outputs[nodeId];
+		if (!entry) continue;
+		for (const kind of params.outputKinds) {
+			const bucket = entry[kind];
+			if (!Array.isArray(bucket)) continue;
+			for (const file of bucket) {
+				if (params.capability === "video" && kind === "images") {
+					const fileName = normalizeOptionalString(file.filename) || normalizeOptionalString(file.name);
+					if (!fileName || !/\.(?:mp4|webm)$/i.test(fileName)) continue;
+				}
+				files.push({
+					nodeId,
+					file
+				});
+			}
+		}
+	}
+	return files;
+}
+async function downloadOutputFile(params) {
+	const fileName = normalizeOptionalString(params.file.filename) || normalizeOptionalString(params.file.name);
+	if (!fileName) throw new Error("Comfy output entry missing filename");
+	const query = new URLSearchParams({
+		filename: fileName,
+		subfolder: normalizeOptionalString(params.file.subfolder) ?? "",
+		type: normalizeOptionalString(params.file.type) ?? "output"
+	});
+	const viewPath = params.mode === "cloud" ? "/api/view" : "/view";
+	const auditContext = `comfy-${params.capability}-download`;
+	const firstResponse = await fetchWithSsrFGuard({
+		url: `${params.baseUrl}${viewPath}?${query.toString()}`,
+		init: {
+			method: "GET",
+			headers: params.headers
+		},
+		timeoutMs: params.timeoutMs,
+		policy: params.policy,
+		dispatcherPolicy: params.dispatcherPolicy,
+		auditContext
+	});
+	try {
+		await assertOkOrThrowHttpError(firstResponse.response, "Comfy output download failed");
+		const mimeType = normalizeOptionalString(firstResponse.response.headers.get("content-type")) || "application/octet-stream";
+		return {
+			buffer: await readResponseWithLimit(firstResponse.response, params.maxBytes, {
+				chunkTimeoutMs: params.timeoutMs,
+				onOverflow: ({ maxBytes }) => /* @__PURE__ */ new Error(`Comfy ${params.capability} output download exceeds ${maxBytes} bytes`),
+				onIdleTimeout: ({ chunkTimeoutMs }) => /* @__PURE__ */ new Error(`Comfy ${params.capability} output download stalled after ${chunkTimeoutMs}ms`)
+			}),
+			mimeType
+		};
+	} finally {
+		await firstResponse.release();
+	}
+}
+function isComfyCapabilityConfigured(params) {
+	const capabilityConfig = getComfyCapabilityConfig(getComfyConfig(params.cfg), params.capability);
+	const hasWorkflow = Boolean(resolveComfyWorkflowSource(capabilityConfig).workflow || normalizeOptionalString(capabilityConfig.workflowPath));
+	const hasPromptNode = Boolean(normalizeOptionalString(capabilityConfig.promptNodeId));
+	if (!hasWorkflow || !hasPromptNode) return false;
+	if (resolveComfyMode(capabilityConfig) === "local") return true;
+	const configuredApiKey = resolveComfyApiKey(capabilityConfig, params.cfg);
+	if (configuredApiKey.status === "available") return true;
+	if (configuredApiKey.status === "configured_unavailable") return false;
+	return isProviderApiKeyConfigured({
+		provider: "comfy",
+		cfg: params.cfg,
+		agentDir: params.agentDir
+	});
+}
+async function runComfyWorkflow(params) {
+	const capabilityConfig = getComfyCapabilityConfig(getComfyConfig(params.cfg), params.capability);
+	const mode = resolveComfyMode(capabilityConfig);
+	const workflow = await loadComfyWorkflow(capabilityConfig);
+	const promptNodeId = getRequiredConfigString(capabilityConfig, "promptNodeId");
+	const promptInputName = normalizeOptionalString(capabilityConfig.promptInputName) ?? DEFAULT_PROMPT_INPUT_NAME;
+	const inputImageNodeId = normalizeOptionalString(capabilityConfig.inputImageNodeId);
+	const inputImageInputName = normalizeOptionalString(capabilityConfig.inputImageInputName) ?? DEFAULT_INPUT_IMAGE_INPUT_NAME;
+	const outputNodeId = normalizeOptionalString(capabilityConfig.outputNodeId);
+	const pollIntervalMs = resolvePositiveTimerTimeoutMs(readConfigInteger(capabilityConfig, "pollIntervalMs"), DEFAULT_POLL_INTERVAL_MS);
+	const timeoutMs = resolvePositiveTimerTimeoutMs(readConfigInteger(capabilityConfig, "timeoutMs") ?? params.timeoutMs, DEFAULT_TIMEOUT_MS);
+	const providerModel = normalizeOptionalString(params.model) || "workflow";
+	setWorkflowInput({
+		workflow,
+		nodeId: promptNodeId,
+		inputName: promptInputName,
+		value: params.prompt
+	});
+	const pluginApiKey = resolveComfyApiKey(capabilityConfig, params.cfg);
+	const resolvedAuth = mode === "cloud" ? pluginApiKey.status === "available" ? {
+		apiKey: pluginApiKey.apiKey,
+		source: pluginApiKey.source,
+		mode: "api-key"
+	} : pluginApiKey.status === "configured_unavailable" ? null : await resolveApiKeyForProvider({
+		provider: "comfy",
+		cfg: params.cfg,
+		agentDir: params.agentDir,
+		store: params.authStore
+	}) : null;
+	if (mode === "cloud" && !resolvedAuth?.apiKey) throw new Error("Comfy Cloud API key missing");
+	const explicitAllowPrivateNetwork = asBoolean(capabilityConfig.allowPrivateNetwork) === true;
+	const { baseUrl, allowPrivateNetwork, headers, dispatcherPolicy } = resolveProviderHttpRequestConfig({
+		baseUrl: normalizeOptionalString(capabilityConfig.baseUrl),
+		defaultBaseUrl: mode === "cloud" ? DEFAULT_COMFY_CLOUD_BASE_URL : DEFAULT_COMFY_LOCAL_BASE_URL,
+		allowPrivateNetwork: mode === "local" || explicitAllowPrivateNetwork,
+		defaultHeaders: mode === "cloud" ? {
+			"X-API-Key": resolvedAuth?.apiKey ?? "",
+			"Content-Type": "application/json"
+		} : { "Content-Type": "application/json" },
+		provider: "comfy",
+		capability: params.capability === "music" ? "audio" : params.capability,
+		transport: "http"
+	});
+	const normalizedBaseUrl = normalizeBaseUrl(baseUrl) || (mode === "cloud" ? DEFAULT_COMFY_CLOUD_BASE_URL : DEFAULT_COMFY_LOCAL_BASE_URL);
+	const networkPolicy = resolveComfyNetworkPolicy({
+		baseUrl: normalizedBaseUrl,
+		allowPrivateNetwork,
+		explicitAllowPrivateNetwork,
+		mode
+	});
+	if (params.inputImage) {
+		if (!inputImageNodeId) throw new Error("Comfy edit requests require plugins.entries.comfy.config.<capability>.inputImageNodeId to be configured");
+		setWorkflowInput({
+			workflow,
+			nodeId: inputImageNodeId,
+			inputName: inputImageInputName,
+			value: await uploadInputImage({
+				baseUrl: normalizedBaseUrl,
+				headers: new Headers(headers),
+				timeoutMs,
+				policy: networkPolicy.apiPolicy,
+				dispatcherPolicy,
+				image: params.inputImage,
+				mode,
+				capability: params.capability
+			})
+		});
+	}
+	const submitPayload = {
+		prompt: workflow,
+		...mode === "cloud" && resolvedAuth?.apiKey ? { extra_data: { api_key_comfy_org: resolvedAuth.apiKey } } : {}
+	};
+	const promptId = normalizeOptionalString((await readJsonResponse({
+		url: `${normalizedBaseUrl}${mode === "cloud" ? "/api/prompt" : "/prompt"}`,
+		init: {
+			method: "POST",
+			headers,
+			body: JSON.stringify(submitPayload)
+		},
+		timeoutMs,
+		policy: networkPolicy.apiPolicy,
+		dispatcherPolicy,
+		auditContext: `comfy-${params.capability}-generate`,
+		errorPrefix: "Comfy workflow submit failed"
+	})).prompt_id);
+	if (!promptId) throw new Error("Comfy workflow submit response missing prompt_id");
+	const historyEntry = extractHistoryEntry(mode === "cloud" ? await (async () => {
+		await waitForCloudCompletion({
+			baseUrl: normalizedBaseUrl,
+			promptId,
+			headers: new Headers(headers),
+			timeoutMs,
+			pollIntervalMs,
+			policy: networkPolicy.apiPolicy,
+			dispatcherPolicy
+		});
+		return await readJsonResponse({
+			url: `${normalizedBaseUrl}/api/history_v2/${promptId}`,
+			init: {
+				method: "GET",
+				headers: new Headers(headers)
+			},
+			timeoutMs,
+			policy: networkPolicy.apiPolicy,
+			dispatcherPolicy,
+			auditContext: "comfy-history",
+			errorPrefix: "Comfy history lookup failed"
+		});
+	})() : await waitForLocalHistory({
+		baseUrl: normalizedBaseUrl,
+		promptId,
+		headers: new Headers(headers),
+		timeoutMs,
+		pollIntervalMs,
+		policy: networkPolicy.apiPolicy,
+		dispatcherPolicy
+	}), promptId);
+	if (!historyEntry) throw new Error(`Comfy history response missing outputs for prompt ${promptId}`);
+	const outputFiles = collectOutputFiles({
+		history: historyEntry,
+		outputNodeId,
+		outputKinds: params.outputKinds,
+		capability: params.capability
+	});
+	if (outputFiles.length === 0) throw new Error(`Comfy workflow ${promptId} completed without ${params.capability} outputs`);
+	const assets = [];
+	const outputKind = params.capability === "music" ? "audio" : params.capability;
+	const maxOutputBytes = resolveGeneratedMediaMaxBytes(params.cfg, outputKind);
+	let assetIndex = 0;
+	for (const output of outputFiles) {
+		const downloaded = await downloadOutputFile({
+			baseUrl: normalizedBaseUrl,
+			headers: new Headers(headers),
+			timeoutMs,
+			policy: networkPolicy.apiPolicy,
+			dispatcherPolicy,
+			file: output.file,
+			mode,
+			capability: params.capability,
+			maxBytes: maxOutputBytes
+		});
+		assetIndex += 1;
+		const originalName = normalizeOptionalString(output.file.filename) || normalizeOptionalString(output.file.name);
+		assets.push({
+			buffer: downloaded.buffer,
+			mimeType: downloaded.mimeType,
+			fileName: originalName || `${params.capability}-${assetIndex}.${resolveFileExtension({ mimeType: downloaded.mimeType })}`,
+			nodeId: output.nodeId
+		});
+	}
+	return {
+		assets,
+		model: providerModel,
+		promptId,
+		outputNodeIds: uniqueStrings(outputFiles.map((entry) => entry.nodeId))
+	};
+}
+//#endregion
+export { DEFAULT_COMFY_MODEL, isComfyCapabilityConfigured, runComfyWorkflow };

package/openclaw.plugin.json

@@ -0,0 +1,273 @@
+{
+  "id": "comfy",
+  "activation": {
+    "onStartup": false
+  },
+  "enabledByDefault": true,
+  "providers": ["comfy"],
+  "setup": {
+    "providers": [
+      {
+        "id": "comfy",
+        "envVars": ["COMFY_API_KEY", "COMFY_CLOUD_API_KEY"]
+      }
+    ]
+  },
+  "providerAuthChoices": [
+    {
+      "provider": "comfy",
+      "method": "cloud-api-key",
+      "choiceId": "comfy-cloud-api-key",
+      "choiceLabel": "Comfy Cloud API key",
+      "choiceHint": "Required for cloud workflows",
+      "groupId": "comfy",
+      "groupLabel": "ComfyUI",
+      "groupHint": "Local or cloud workflows",
+      "optionKey": "comfyApiKey",
+      "cliFlag": "--comfy-api-key",
+      "cliOption": "--comfy-api-key <key>",
+      "cliDescription": "Comfy Cloud API key",
+      "onboardingScopes": ["image-generation"]
+    }
+  ],
+  "contracts": {
+    "imageGenerationProviders": ["comfy"],
+    "musicGenerationProviders": ["comfy"],
+    "videoGenerationProviders": ["comfy"]
+  },
+  "imageGenerationProviderMetadata": {
+    "comfy": {
+      "configSignals": [
+        {
+          "rootPath": "plugins.entries.comfy.config",
+          "overlayPath": "image",
+          "mode": {
+            "path": "mode",
+            "default": "local",
+            "allowed": ["local"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId"]
+        },
+        {
+          "rootPath": "models.providers.comfy",
+          "overlayPath": "image",
+          "mode": {
+            "path": "mode",
+            "default": "local",
+            "allowed": ["local"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId"]
+        },
+        {
+          "rootPath": "plugins.entries.comfy.config",
+          "overlayPath": "image",
+          "mode": {
+            "path": "mode",
+            "allowed": ["cloud"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId", "apiKey"]
+        },
+        {
+          "rootPath": "models.providers.comfy",
+          "overlayPath": "image",
+          "mode": {
+            "path": "mode",
+            "allowed": ["cloud"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId", "apiKey"]
+        }
+      ]
+    }
+  },
+  "musicGenerationProviderMetadata": {
+    "comfy": {
+      "configSignals": [
+        {
+          "rootPath": "plugins.entries.comfy.config",
+          "overlayPath": "music",
+          "mode": {
+            "path": "mode",
+            "default": "local",
+            "allowed": ["local"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId"]
+        },
+        {
+          "rootPath": "models.providers.comfy",
+          "overlayPath": "music",
+          "mode": {
+            "path": "mode",
+            "default": "local",
+            "allowed": ["local"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId"]
+        },
+        {
+          "rootPath": "plugins.entries.comfy.config",
+          "overlayPath": "music",
+          "mode": {
+            "path": "mode",
+            "allowed": ["cloud"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId", "apiKey"]
+        },
+        {
+          "rootPath": "models.providers.comfy",
+          "overlayPath": "music",
+          "mode": {
+            "path": "mode",
+            "allowed": ["cloud"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId", "apiKey"]
+        }
+      ]
+    }
+  },
+  "videoGenerationProviderMetadata": {
+    "comfy": {
+      "configSignals": [
+        {
+          "rootPath": "plugins.entries.comfy.config",
+          "overlayPath": "video",
+          "mode": {
+            "path": "mode",
+            "default": "local",
+            "allowed": ["local"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId"]
+        },
+        {
+          "rootPath": "models.providers.comfy",
+          "overlayPath": "video",
+          "mode": {
+            "path": "mode",
+            "default": "local",
+            "allowed": ["local"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId"]
+        },
+        {
+          "rootPath": "plugins.entries.comfy.config",
+          "overlayPath": "video",
+          "mode": {
+            "path": "mode",
+            "allowed": ["cloud"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId", "apiKey"]
+        },
+        {
+          "rootPath": "models.providers.comfy",
+          "overlayPath": "video",
+          "mode": {
+            "path": "mode",
+            "allowed": ["cloud"]
+          },
+          "requiredAny": ["workflow", "workflowPath"],
+          "required": ["promptNodeId", "apiKey"]
+        }
+      ]
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "mode": {
+        "type": "string",
+        "enum": ["local", "cloud"]
+      },
+      "baseUrl": {
+        "type": "string"
+      },
+      "apiKey": {
+        "type": ["string", "object"]
+      },
+      "allowPrivateNetwork": {
+        "type": "boolean"
+      },
+      "workflowPath": {
+        "type": "string"
+      },
+      "workflow": {
+        "type": "object"
+      },
+      "promptNodeId": {
+        "type": "string"
+      },
+      "promptInputName": {
+        "type": "string"
+      },
+      "inputImageNodeId": {
+        "type": "string"
+      },
+      "inputImageInputName": {
+        "type": "string"
+      },
+      "outputNodeId": {
+        "type": "string"
+      },
+      "pollIntervalMs": {
+        "type": "integer",
+        "minimum": 100
+      },
+      "timeoutMs": {
+        "type": "integer",
+        "minimum": 1000
+      },
+      "image": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "workflowPath": { "type": "string" },
+          "workflow": { "type": "object" },
+          "promptNodeId": { "type": "string" },
+          "promptInputName": { "type": "string" },
+          "inputImageNodeId": { "type": "string" },
+          "inputImageInputName": { "type": "string" },
+          "outputNodeId": { "type": "string" },
+          "pollIntervalMs": { "type": "integer", "minimum": 100 },
+          "timeoutMs": { "type": "integer", "minimum": 1000 }
+        }
+      },
+      "video": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "workflowPath": { "type": "string" },
+          "workflow": { "type": "object" },
+          "promptNodeId": { "type": "string" },
+          "promptInputName": { "type": "string" },
+          "inputImageNodeId": { "type": "string" },
+          "inputImageInputName": { "type": "string" },
+          "outputNodeId": { "type": "string" },
+          "pollIntervalMs": { "type": "integer", "minimum": 100 },
+          "timeoutMs": { "type": "integer", "minimum": 1000 }
+        }
+      },
+      "music": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "workflowPath": { "type": "string" },
+          "workflow": { "type": "object" },
+          "promptNodeId": { "type": "string" },
+          "promptInputName": { "type": "string" },
+          "outputNodeId": { "type": "string" },
+          "pollIntervalMs": { "type": "integer", "minimum": 100 },
+          "timeoutMs": { "type": "integer", "minimum": 1000 }
+        }
+      }
+    }
+  }
+}

package/package.json

@@ -1,14 +1,49 @@
 {
   "name": "@openclaw/comfy-provider",
-  "version": "0.0.0",
-  "description": "Reserved package name for an official OpenClaw plugin.",
-  "license": "MIT",
+  "version": "2026.8.1-beta.2",
+  "description": "OpenClaw ComfyUI provider plugin.",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/openclaw/openclaw.git"
+    "url": "https://github.com/openclaw/openclaw"
   },
-  "publishConfig": {
-    "access": "public",
-    "tag": "placeholder"
-  }
+  "type": "module",
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "clawhubSpec": "clawhub:@openclaw/comfy-provider",
+      "npmSpec": "@openclaw/comfy-provider",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.7.2"
+    },
+    "compat": {
+      "pluginApi": ">=2026.8.1-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.8.1-beta.2",
+      "bundledDist": false
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    },
+    "runtimeExtensions": [
+      "./dist/index.js"
+    ]
+  },
+  "files": [
+    "dist/**",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "openclaw": ">=2026.8.1-beta.2"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "bundledDependencies": []
 }