Image Tool Silently Broken After OpenClaw Upgrade — Missing imageModel and sessions_spawn.attachments.enabled Configurations

Primary Error: Image Model Not Configured

When invoking the image tool against any image file, the operation fails with the following error regardless of whether a model argument is provided:

{
  "error": "No image model is configured. Set agents.defaults.imageModel or configure an image-capable provider."
}

CLI reproduction attempt:

$ openclaw infer image describe --file /path/to/image.jpg
Error: No image model is configured. Set agents.defaults.imageModel or configure an image-capable provider.

$ openclaw infer image describe --file /path/to/image.jpg --model opencode-go/mimo-v2.5
Error: No image model is configured. Set agents.defaults.imageModel or configure an image-capable provider.

Secondary Error: Attachments Disabled for sessions_spawn

When the orchestrator attempts to route the image to a multimodal subagent via sessions_spawn, the fallback fails with:

{
  "error": "attachments are disabled for sessions_spawn (enable tools.sessions_spawn.attachments.enabled)"
}

JSON tool call example:

{
  "name": "sessions_spawn",
  "arguments": {
    "agentId": "multimodal",
    "attachments": [{"path": "/path/file.jpg", "type": "image/jpeg"}],
    "task": "describe this image"
  }
}

Diagnostic Discrepancy

Running openclaw doctor completes without warnings, even when a vision-capable model (e.g., opencode-go/mimo-v2.5) is configured for another agent:

$ openclaw doctor
✓ Configuration loaded successfully
✓ All agents initialized
✓ Gateway connection established
✓ Doctor check complete — no issues found

Cascading Belief Corruption

Agents that have previously encountered the image failure cache the “model not configured” error in their conversation history. After the operator corrects the configuration, the agent continues to refuse image operations without explicit intervention.

Architectural Change: Strict Configuration Validation

Between OpenClaw v4.22 and v5.7 (likely introduced in v5.2), a strict configuration validator was introduced that made previously implicit defaults mandatory. This change was not accompanied by:

• A migration script
• Release note documentation
• Warning output from openclaw doctor

Configuration Dependency Chain

The image tool follows this decision tree:

┌─────────────────────────────────────────────────────────────────┐ │ image tool invocation │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌───────────────────────────────┐ │ model argument provided? │ └───────────────────────────────┘ │ │ YES NO │ │ ▼ ▼ ┌─────────────────┐ ┌─────────────────────────────┐ │ Honor per-call │ │ Check agents.defaults. │ │ override │ │ imageModel │ └─────────────────┘ └─────────────────────────────┘ │ │ SET UNSET │ │ ▼ ▼ ┌─────────────┐ ┌──────────────────────┐ │ Use model │ │ Hard-fail with error │ └─────────────┘ │ (per-call override │ │ is NOT consulted) │ └──────────────────────┘

Critical Bug: The per-call model override is not consulted when agents.defaults.imageModel is unset. The tool fails before evaluating the per-call argument.

sessions_spawn Attachments Requirement

The sessions_spawn tool, which enables orchestrator-to-subagent routing, now requires explicit opt-in for attachment passthrough:

json “tools”: { “sessions_spawn”: { “attachments”: { “enabled”: false // Default changed to false; must be explicitly true } } }

This breaks the multimodal fallback pipeline where the orchestrator would previously route image attachments directly to a vision-capable subagent.

Files Involved

Version Timeline

Phase 1: Identify Your Vision-Capable Model

List all configured agents and identify which one has vision capabilities:

$ openclaw config get agents --format=json | jq '.[] | select(.model | test("mimo|vision|gpt-4v|claude-3.*vision"; "i"))'

Phase 2: Update Configuration

Locate your openclaw.json configuration file (typically at ~/.config/openclaw/openclaw.json or ./openclaw.json):

Before (pre-v5.2 implicit configuration): json { “agents”: { “orchestrator”: { “model”: “opencode-go/kimi-k2.6” }, “multimodal”: { “model”: “opencode-go/mimo-v2.5” } } }

After (v5.7+ required explicit configuration): json { “agents”: { “defaults”: { “imageModel”: “opencode-go/mimo-v2.5” }, “orchestrator”: { “model”: “opencode-go/kimi-k2.6” }, “multimodal”: { “model”: “opencode-go/mimo-v2.5” } }, “tools”: { “sessions_spawn”: { “attachments”: { “enabled”: true } } } }

Phase 3: Restart Gateway

After modifying the configuration, restart the OpenClaw gateway service:

# If running as systemd service
$ sudo systemctl restart openclaw

# Or if running directly
$ openclaw gateway stop && openclaw gateway start

Phase 4: Clear Agent Conversation History (If Required)

If agents have cached the failure belief, clear the relevant conversation history:

# List active sessions
$ openclaw sessions list

# Clear specific session cache
$ openclaw sessions clear --session-id <session-id>

# Or clear all cached beliefs for the image tool
$ openclaw memory purge --tool image

Then nudge the agent:

“The image tool is now configured. Please retry the image analysis.”

Phase 5: Verify Configuration Persists

$ openclaw config get agents.defaults.imageModel
opencode-go/mimo-v2.5

$ openclaw config get tools.sessions_spawn.attachments.enabled
true

Test 1: Direct Image Tool Invocation

$ openclaw infer image describe --file /path/to/test.jpg --timeout-ms 60000
✓ Image analysis complete
✓ Model: opencode-go/mimo-v2.5
✓ Response generated successfully

Test 2: Per-Call Model Override

$ openclaw infer image describe --file /path/to/test.jpg --model opencode-go/mimo-v2.5 --timeout-ms 60000
✓ Image analysis complete
✓ Model: opencode-go/mimo-v2.5
✓ Response matches Test 1

Test 3: sessions_spawn Attachment Routing

$ openclaw eval tool-calls --input '{"name":"sessions_spawn","arguments":{"agentId":"multimodal","attachments":[{"path":"/path/test.jpg","type":"image/jpeg"}],"task":"describe"}}'
✓ sessions_spawn completed
✓ Attachment forwarded to multimodal agent
✓ Response received

Test 4: Orchestrator Image Fallback

Send a message to the orchestrator agent requesting image description:

$ openclaw chat --agent orchestrator --message "Describe the image at /path/to/test.jpg"
✓ Agent invoked image tool
✓ Vision model responded
✓ Description returned to user

Test 5: Verify openclaw doctor Now Detects Configuration

$ openclaw doctor
✓ Configuration loaded successfully
✓ agents.defaults.imageModel is set to: opencode-go/mimo-v2.5
✓ tools.sessions_spawn.attachments.enabled is: true
✓ All vision-related checks passed
✓ Doctor check complete

Expected exit code: 0

Test 6: End-to-End Multimodal Pipeline

$ openclaw infer --agent orchestrator "Analyze this image and explain what you see: /path/to/test.jpg"
[Orchestrator reasoning]
[Orchestrator spawned multimodal subagent]
[Multimodal agent responded with description]
✓ End-to-end pipeline verified

1. Stale Conversation Beliefs

Problem: Agents cache the “model not configured” error in their conversation history. Even after fixing openclaw.json, the agent refuses to retry.

Workaround:

• Clear the session: openclaw sessions clear --session-id <id>
• Or manually nudge: “Image tool is now configured, please retry”
• Or use openclaw memory purge --tool image

2. Short Default Timeout

Problem: The CLI default timeout is 7 seconds, insufficient for vision models like mimo-v2.5.

Workaround: Always specify --timeout-ms 60000 or higher for image operations: bash openclaw infer image describe –file image.jpg –timeout-ms 60000

3. Configuration File Location Confusion

Problem: openclaw.json may exist in multiple locations, causing confusion about which is active.

Verification:

$ openclaw config locate
/home/user/.config/openclaw/openclaw.json

$ openclaw config get --source
/home/user/.config/openclaw/openclaw.json

4. Docker Environment Variable Override

Problem: In Docker deployments, OPENCLAW_CONFIG_PATH may override the expected config file.

Verification:

$ docker exec <container> env | grep OPENCLAW

5. Partial Migration

Problem: Adding imageModel but not sessions_spawn.attachments.enabled — the direct path works but fallback routing fails.

Check both are set: bash openclaw config get tools.sessions_spawn.attachments.enabled # Should return true

6. Model Name vs. Provider Alias

Problem: Using mimo instead of opencode-go/mimo-v2.5 may cause resolution failures.

Always use fully-qualified model names in agents.defaults.imageModel.

7. Upgrade Without Restart

Problem: Configuration changes require gateway restart; hot-reload does not apply to config schema changes.

Always restart after config modifications: bash openclaw gateway restart

Directly Related

Historically Related (Same Family: Implicit Default Removal)

Configuration Schema Changes in v5.2+

Known Affected Versions

• Confirmed broken: v5.2, v5.3, v5.4, v5.5, v5.6, v5.7
• Confirmed working: ≤ v4.22
• Untested: v4.23 – v5.1 (likely affected if strict validator landed in v5.2)