openclaw - 💡(How to fix) Fix [Bug]: image tool silently broken post-upgrade — agents.defaults.imageModel and tools.sessions_spawn.attachments.enabled now required without migration

Bug type

Behavior change without release notes / UX regression — file is to clarify intent and request a migration path.

Beta release blocker

No (workarounds exist).

Summary

On hosts upgraded from earlier OpenClaw releases, the image tool now hard-fails on every invocation with "No image model is configured. Set agents.defaults.imageModel or configure an image-capable provider." even though a vision-capable model (opencode-go/mimo-v2.5 in our case, used by a multimodal subagent) is configured and reachable. The error appears whether or not the calling agent passes a model argument explicitly — per-call override is ignored when agents.defaults.imageModel is unset.

A separate but coupled issue: when an orchestrator agent tries to fall back by routing the attachment to a multimodal subagent via sessions_spawn with attachments, the call is rejected with "attachments are disabled for sessions_spawn (enable tools.sessions_spawn.attachments.enabled)". Both keys default in a way that silently breaks the multimodal pipeline post-upgrade.

Why this matters

• The image tool's previous behavior (on this host's earlier OpenClaw versions) Just Worked — no explicit imageModel was ever set in any of our config backups going back to v4.22, yet image-handling functioned. Some recent release (likely the v5.2 strict config validator or a related change) made the explicit key required without a migration path or release-note callout.
• openclaw doctor does not flag the missing imageModel even when a vision-capable model is configured under another agent; and it does not warn when tools.sessions_spawn.attachments.enabled is missing while one or more agents are explicitly set up as multimodal handlers.
• An orchestrator agent that has previously failed an image-tool call in a long-running session caches the "model not configured" belief in its conversation history, so even after the operator fixes the config, the agent often refuses to retry without an explicit nudge — silent regression spreads across hours of conversation.

Reproduction (deterministic on v2026.5.7)

1. Upgrade from a pre-v5.2 OpenClaw release to v5.7. Don't add agents.defaults.imageModel to openclaw.json (it was implicit before, no migration is offered).
2. Configure at least one agent with a vision-capable model (e.g. opencode-go/mimo-v2.5).
3. From any other agent, call the image tool against a real .jpg/.png file — with or without a model argument:

   {"name":"image","arguments":{"image":"/path/file.jpg","prompt":"describe"}}
   {"name":"image","arguments":{"image":"/path/file.jpg","model":"opencode-go/mimo-v2.5","prompt":"describe"}}

4. Both return "No image model is configured. Set agents.defaults.imageModel or configure an image-capable provider.".
5. Try to fall back via sessions_spawn with attachments:

   {"name":"sessions_spawn","arguments":{"agentId":"multimodal","attachments":[{...}],"task":"describe"}}

   Returns "attachments are disabled for sessions_spawn (enable tools.sessions_spawn.attachments.enabled)".
6. The orchestrator agent gives up and asks the user to paste image content as text instead.

Workaround (proven on v2026.5.7)

Add to openclaw.json and restart gateway:

{
  "agents": {
    "defaults": {
      "imageModel": "opencode-go/mimo-v2.5"
    }
  },
  "tools": {
    "sessions_spawn": {
      "attachments": {
        "enabled": true
      }
    }
  }
}

Verified end-to-end: openclaw infer image describe --file <jpg> --timeout-ms 60000 returns a correct vision description. (CLI default timeout is 7s, which is too short for mimo-v2.5 — that's a separate UX nit; setting --timeout-ms 60000 works, and the in-agent tool call uses a longer default of ~30s which is also fine.)

After the config change, an orchestrator that previously refused images may still cache the failure belief and not retry until the operator explicitly nudges it ("the image tool is configured now, please try again"). That stale-belief problem is downstream of the config issue but worth noting.

Suggested fixes

1. openclaw doctor: when imageModel is unset but at least one agent has a vision-capable primary/fallback model, surface a warning and offer --fix to populate agents.defaults.imageModel with that model. Same pattern as the v5.2 strict-validator migrations for agents.defaults.llm and threadBindings.spawnSubagentSessions.
2. openclaw doctor: warn when tools.sessions_spawn.attachments.enabled is unset and any agent is configured with a vision-capable model — the orchestrator may need attachment routing.
3. Per-call model override: if the agent passes model: to the image tool, honor it before falling back to agents.defaults.imageModel. Currently the per-call override appears to be ignored when the default is unset (we observed identical errors with and without explicit model).
4. Error message: the "No image model is configured" message could nudge toward openclaw doctor --fix rather than "Set X or configure Y" — operators don't always know which path applies.
5. Release notes: a one-liner in the release that introduced this requirement would have saved upgrade-verification time across the user base.

Environment

• OpenClaw: 2026.5.7 (eeef486). First observed today on this version; backup audit confirms imageModel was never set in any prior config back to v4.22, suggesting the implicit-default removal landed somewhere between v4.22 and v5.7. Strong candidate is the v5.2 strict config validator.
• OS: Ubuntu 24.04 / Linux 6.8.0-110-generic x86_64
• Node: v22.22.2
• Install: npm global as systemd service
• Topology: 5-agent (orchestrator + reasoner + coder + fast + multimodal); the orchestrator (opencode-go/kimi-k2.6) attempted the failed image calls; the multimodal agent (opencode-go/mimo-v2.5) is the working vision provider.

Related

• #79263 — v4.29+ CLI local-transport stops reading ~/.env (also a behavior change without release notes; same family of "implicit default removed without migration").
• #61789 (CLOSED) — image tool / provider alias parsing; different mechanism, mentioning to disambiguate.
• #73424 — image preprocessing pipeline failure; different layer.
• #77090 — image-related auto-revert feature request; tangential.