← All Articles

OpenClaw HEIC Normalization: Cross-Platform Image Handling

A small gateway fix solves a frustrating problem: iOS photos can now be processed by any backend, not just Apple-native ones.

The Problem

Since iOS 11 (2017), iPhones save photos in HEIC format by default. HEIC offers better compression than JPEG while maintaining quality — Apple made a smart technical choice.

The challenge: most non-Apple software can't read HEIC natively. This creates friction when iPhone users send photos to AI assistants running on Linux servers or Windows backends. The image arrives, the server doesn't know what to do with it, and the user gets an error.

What Changed

The fix adds HEIC detection and conversion at the gateway layer — the earliest possible point in the image processing pipeline:

1. Incoming images are checked for HEIC/HEIF format
2. HEIC images are converted to JPEG before being passed to providers
3. The conversion happens transparently — no user or skill changes required

By handling this in the gateway, every downstream consumer benefits automatically. Vision models, image generation tools, and storage systems all receive universally-compatible JPEG.

Technical Details

The implementation leverages existing image processing libraries to:

• Detect HEIC via magic bytes (not just file extension)
• Preserve EXIF metadata during conversion
• Maintain reasonable quality/size tradeoffs
• Handle edge cases like HEIC sequences (Live Photos)

The PR also updates the input_image normalization path, ensuring consistency with how other image formats are handled.

Why Gateway-Level Matters

OpenClaw could have addressed HEIC support in several places:

• Client apps: Convert before sending (requires updating every client)
• Individual skills: Each skill handles its own conversion (code duplication)
• Provider adapters: Convert before model inference (still reaches storage as HEIC)
• Gateway: Convert once, early, benefiting everything downstream ✓

The gateway approach embodies "do one thing well" — image normalization becomes infrastructure that other components can rely on.

Implications

For OpenClaw users:

• iPhone photos "just work" without any configuration
• No need to change camera settings or use third-party apps
• Existing workflows continue unchanged

For OpenClaw developers:

• Skills can assume images arrive in web-friendly formats
• Less defensive coding around format detection
• Consistent behavior across all image sources

This commit is part of a broader pattern in OpenClaw: pushing complexity to infrastructure layers so that higher-level code can focus on user value.