OpenClaw imageModel Setup: A Complete Configuration Guide for 2026

Most AI coding assistants treat every message the same way — routing all input through a single model regardless of whether it contains text, an image, or a scanned PDF. OpenClaw takes a different approach, letting developers assign distinct models to distinct content types. The imageModel configuration is the clearest expression of that philosophy.

What imageModel Does and Why It Exists Separately

imageModel is OpenClaw's dedicated configuration field for visual processing. When a conversation includes an image — a screenshot, a photo, a diagram — OpenClaw doesn't attempt to run it through the primary text model. Instead, it routes the content to whichever model is specified under imageModel, then returns to the primary model for everything else.

The reason this separation matters is practical. Fast, cost-effective text models like MiniMax-M2.5-highspeed are optimized for language tasks and cannot process visual input at all. Multimodal models like moonshot/kimi-k2.5 can handle both — but running every conversation through a heavier multimodal model adds latency and cost that most text-only interactions don't justify. The imageModel field resolves this tension cleanly: text goes fast, images go capable.

How to Configure imageModel — Two Paths

OpenClaw supports two methods for setting up vision model routing. The first is direct config file editing via openclaw config edit. The second is the CLI, which lets you manage everything without touching JSON directly.

Within the config file, the imageModel field accepts two syntax formats. The shorthand assigns a single primary model:

"imageModel": "moonshot/kimi-k2.5"

The full syntax adds a fallback chain, which is the recommended approach for production use:

"imageModel": {
"primary": "moonshot/kimi-k2.5",
"fallbacks": ["openrouter/google/gemini-2.0-flash-vision:free"]
}

For CLI-based management, OpenClaw provides a focused set of commands:

# View current imageModel status
openclaw models status
# Set imageModel primary model
openclaw models set-image moonshot/kimi-k2.5
# Manage imageModel fallback chain
openclaw models image-fallbacks list
openclaw models image-fallbacks add openrouter/qwen/qwen-2.5-vl-72b-instruct:free
openclaw models image-fallbacks remove openrouter/qwen/qwen-2.5-vl-72b-instruct:free
openclaw models image-fallbacks clear

When imageModel isn't configured at all but a provider API key is detected, OpenClaw falls back to built-in defaults. These vary by provider:

Where imageModel Gets Triggered — and How PDF Handling Fits In

The imageModel activates across four distinct scenarios: when a user sends a photo or screenshot, when media understanding pipelines receive image or video frame data, when an agent uses the built-in image tool internally, and — under specific conditions — when a PDF arrives.

That last scenario deserves attention. PDF handling in OpenClaw follows a strict priority chain:

pdfModel → imageModel → built-in provider default

If pdfModel is not configured, the system doesn't fail — it silently falls back to imageModel. This means a single vision model configuration can serve double duty across image attachments and scanned document pages without any additional setup.

The fallback chain for imageModel itself works sequentially: OpenClaw tries imageModel.primary first, then each entry in imageModel.fallbacks in order, returning the first successful response. If every model in the chain fails, the system surfaces a clear error: "No image model configured. Set agents.defaults.imageModel.primary or agents.defaults.imageModel.fallbacks."

What This Design Philosophy Signals for AI Tooling

The imageModel pattern reflects a broader architectural trend worth paying attention to: the move away from monolithic AI backends toward modular, content-aware routing. Rather than forcing developers to choose between a fast model and a capable one, OpenClaw lets them maintain both simultaneously and route inputs based on what the content actually requires.

This matters because multimodal AI usage is no longer a niche case. Screenshots, diagrams, and scanned documents are common inputs in real developer workflows. A system that routes all of that through the same text-optimized model either fails outright or forces an expensive upgrade to a heavier model for every interaction. OpenClaw's separation sidesteps that tradeoff entirely.

A complete configuration pulling these threads together would look like this:

{
"agents": {
"defaults": {
"model": {
"primary": "minimax-portal/MiniMax-M2.5-highspeed",
"fallbacks": ["moonshot/kimi-k2.5", "anthropic/claude-opus-4-6"]
},
"imageModel": {
"primary": "moonshot/kimi-k2.5",
"fallbacks": ["openrouter/google/gemini-2.0-flash-vision:free"]
},
"pdfModel": {
"primary": "anthropic/claude-opus-4-6"
},
"models": {
"moonshot/kimi-k2.5": {
"alias": "kimi"
},
"minimax-portal/MiniMax-M2.5-highspeed": {
"alias": "mm"
}
}
}
}
}

For developers building workflows that mix heavy text processing with occasional visual analysis, this kind of modular configuration isn't just a convenience — it's the difference between a system optimized for real-world usage and one that forces compromises on every request.