diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json
index 8170ebdb5..4c0ae5164 100644
--- a/.openclaw-sync/source.json
+++ b/.openclaw-sync/source.json
@@ -1,5 +1,5 @@
 {
   "repository": "openclaw/openclaw",
-  "sha": "62997f7fcec19c22b60856d5c1fc16df472e2c4f",
-  "syncedAt": "2026-04-28T09:08:49.411Z"
+  "sha": "fac116cfa42682bf20636c1e165b513e19ca5240",
+  "syncedAt": "2026-04-28T09:19:13.832Z"
 }
diff --git a/docs/gateway/config-agents.md b/docs/gateway/config-agents.md
index 44fc5f494..b9c2eaf65 100644
--- a/docs/gateway/config-agents.md
+++ b/docs/gateway/config-agents.md
@@ -342,6 +342,7 @@ Time format in system prompt. Default: `auto` (OS preference).
 - `imageModel`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
   - Used by the `image` tool path as its vision-model config.
   - Also used as fallback routing when the selected/default model cannot accept image input.
+  - Prefer explicit `provider/model` refs. Bare IDs are accepted for compatibility; if a bare ID uniquely matches a configured image-capable entry in `models.providers.*.models`, OpenClaw qualifies it to that provider. Ambiguous configured matches require an explicit provider prefix.
 - `imageGenerationModel`: accepts either a string (`"provider/model"`) or an object (`{ primary, fallbacks }`).
   - Used by the shared image-generation capability and any future tool/plugin surface that generates images.
   - Typical values: `google/gemini-3.1-flash-image-preview` for native Gemini image generation, `fal/fal-ai/flux/dev` for fal, `openai/gpt-image-2` for OpenAI Images, or `openai/gpt-image-1.5` for transparent-background OpenAI PNG/WebP output.
diff --git a/docs/nodes/media-understanding.md b/docs/nodes/media-understanding.md
index df4cf5bbe..9a685763f 100644
--- a/docs/nodes/media-understanding.md
+++ b/docs/nodes/media-understanding.md
@@ -172,6 +172,7 @@ If `tools.media.<capability>.enabled` is **not** set to `false` and you haven't
   </Step>
   <Step title="agents.defaults.imageModel">
     `agents.defaults.imageModel` primary/fallback refs (image only).
+    Prefer `provider/model` refs. Bare refs are qualified from configured image-capable provider model entries only when the match is unique.
   </Step>
   <Step title="Local CLIs (audio only)">
     Local CLIs (if installed):
diff --git a/docs/providers/ollama.md b/docs/providers/ollama.md
index 427a6108a..c6a243b43 100644
--- a/docs/providers/ollama.md
+++ b/docs/providers/ollama.md
@@ -283,6 +283,8 @@ To make Ollama the default image-understanding model for inbound media, configur
 }
 ```
 
+Prefer the full `ollama/<model>` ref. If the same model is listed under `models.providers.ollama.models` with `input: ["text", "image"]` and no other configured image provider exposes that bare model ID, OpenClaw also normalizes a bare `imageModel` ref such as `qwen2.5vl:7b` to `ollama/qwen2.5vl:7b`. If more than one configured image provider has the same bare ID, use the provider prefix explicitly.
+
 Slow local vision models can need a longer image-understanding timeout than cloud models. They can also crash or stop when Ollama tries to allocate the full advertised vision context on constrained hardware. Set a capability timeout, and cap `num_ctx` on the model entry when you only need a normal image-description turn:
 
 ```json5