MOSSImageHFLoader

What MOSSImageHFLoader does

The node loads the MOSS-Image transformer, Qwen text encoder, tokenizer, and VAE from one local model directory. It returns standard MODEL, CLIP, and VAE outputs for the rest of the ComfyUI graph. It does not accept a Hugging Face Hub repository ID and does not download model files for you.

your-model-directory/
├── transformer/
├── text_encoder/
├── tokenizer/
└── vae/

The component directories may contain single or sharded safetensors files plus their configuration files. Keep the repository structure intact.

Choose native ComfyUI or the HF loader

The two workflow types use different sampling graphs and timestep multipliers. Do not convert one by replacing only its loader. If you are starting fresh, follow the native installation path.

Install the official HF-directory plugin

Clone or download the official OpenMOSS MOSS-Image repository, then choose one installation method.

Copy the node directory

cp -r comfyui/moss-image/ /path/to/ComfyUI/custom_nodes/moss-image/

Run the official installer

python comfyui/install.py --comfy-root /path/to/ComfyUI

The installer creates a relative link at custom_nodes/moss-image. It also copies the official plugin workflow into user/default/workflows when a file with the same name is not already there. Restart ComfyUI after installation.

The plugin uses ComfyUI's dependencies. If startup reports an import error, update the ComfyUI environment and compare it with the current requirements documented by OpenMOSS instead of installing an unverified requirements file.

Configure model_path

1. Download the complete MOSS-Image Base or MOSS-Image SFT repository.
2. Add MOSSImageHFLoader to the graph or import the matching official plugin workflow.
3. Set model_path to the directory containing transformer/, text_encoder/, tokenizer/, and vae/.
4. Queue one fixed-seed 1024 × 1024 test before changing the graph.

An absolute path avoids ambiguity:

/home/user/models/MOSS-Image-SFT

A relative path is resolved from the ComfyUI process working directory, which depends on how ComfyUI was launched.

Node options

The loader reads transformer weights from the transformer directory, Qwen3.5 weights from text_encoder, tokenizer data from tokenizer, and VAE weights from vae. The VAE is loaded in FP32, and text encoding is capped at 4096 tokens.

Troubleshooting

The node does not appear

Confirm that ComfyUI/custom_nodes/moss-image/ resolves to the official node directory. Fully restart ComfyUI and inspect the startup log for API or dependency errors.

model_path is invalid or a file is missing

Point to the parent directory containing all four component folders, not to a safetensors file or an individual component folder. Confirm that the ComfyUI process can read the path.

The workflow runs out of memory

Reduce canvas dimensions, try a supported FP8 mode when suitable for your hardware, or set text_device to CPU. The best option depends on GPU support and the current ComfyUI memory manager.

The output differs from the online studio

The online studio submits to a hosted SFT endpoint with 50 inference steps. Its infrastructure and numerical precision are controlled by the provider. The plugin scheduler also differs from the standalone pipeline, so matching a seed does not guarantee a pixel-identical image.

Text is imperfect

Shorten the requested wording, quote exact text, use explicit line breaks when needed, and proofread every result before publishing.