Summary

What problem does this PR solve?

OpenClaw's Qwen image-understanding routing had two coupled failure points for DashScope:

1. The resolver trusted configured/catalog input: ["text", "image"] metadata as sufficient proof that a Qwen model could handle image content. That allowed known text-only Qwen chat models such as qwen3.7-max to be selected for image requests when config metadata was overly broad.
2. Qwen/DashScope modelstudio-native image requests did not use the same prompt placement as OpenRouter-style multimodal providers, so the image prompt could be sent as a separate system/developer prompt instead of user content before the image block.

Together, that can produce DashScope's 400 Unexpected item type in content for an image-understanding request instead of routing to the bundled Qwen vision default.

Why does this matter now?

A valid Qwen setup can lose the user's image request before an image-capable model is reached. The reported path configured Qwen/DashScope with a chat model such as qwen3.7-max; image understanding should skip that text-only family and select qwen-vl-max-latest.

What is the intended outcome?

Fix classification: root-cause fix. Qwen provider-owned runtime metadata now marks the known text-only family as non-image for media-understanding routing, and the resolver entry points consume that metadata before accepting configured image metadata. DashScope-native image prompts are placed in the user content before the image block.

What is intentionally out of scope?

Scope boundary: this PR does not change Qwen auth, API-key lookup, network transport, public plugin SDK shape, public manifest schema, migrations, or provider endpoint selection. The Qwen-specific capability fact stays internal to the Qwen provider/runtime metadata.

What does success look like?

When config marks qwen3.7-max as [text,image], OpenClaw still resolves image understanding to qwen/qwen-vl-max-latest, and Qwen/DashScope image prompts are serialized as user text before the image payload.

What should reviewers focus on?

Please check the source-of-truth boundary and resolver consistency: Qwen model capability facts are provider-owned runtime metadata, not a new public manifest/plugin SDK contract, and the same filtering rule is applied across default media model resolution, configured provider discovery, image-tool routing, PDF-tool routing, manifest-backed defaults, and bundled Qwen aliases.

Linked context

Closes #92688.

This refresh addresses the review concern that the previous shape risked making a Qwen-specific model fact part of a broader public contract. The current shape keeps the compatibility-sensitive decision in internal provider/runtime metadata while preserving the existing public manifest metadata surface for capabilities and defaults.

Real behavior proof (required for external PRs)

• Behavior or issue addressed: image routing must select an image-capable Qwen model when the active/configured Qwen chat model is qwen3.7-max and its configured metadata incorrectly includes image.

• Real environment tested: OpenClaw's resolver and image-tool/media-understanding paths with Qwen/DashScope-style config, provider registry construction, manifest-backed defaults, and bundled Qwen image defaults.

• Exact steps or command run after this patch: configured the active model as qwen/qwen3.7-max, configured the Qwen provider model entry as input: ["text", "image"], then exercised the OpenClaw resolver/image-tool paths.

• Evidence after fix:

configured active model: qwen/qwen3.7-max
configured provider metadata: qwen3.7-max declares input [text,image]
resolved image model primary: qwen/qwen-vl-max-latest
PASS: qwen3.7-max was not selected for image understanding; Qwen vision default was selected.

tool result text: qwen image ok
image tool describeImageWithModel call: {"provider":"qwen","model":"qwen-vl-max-latest","prompt":"Describe the image.","mime":"image/png"}
PASS: image tool invoked Qwen media understanding with qwen-vl-max-latest instead of qwen3.7-max.

resolved manifest-backed default: qwen-vl-max-latest
PASS: manifest-backed Qwen default resolver skipped qwen3.7-max and selected qwen-vl-max-latest.

• Observed result after fix: the active/configured chat model can remain qwen/qwen3.7-max, the configured provider metadata can still declare qwen3.7-max as [text,image], and the image request path selects qwen/qwen-vl-max-latest.
• What was not tested: this proof validates the OpenClaw routing and request-shaping decisions for [Bug]: Qwen vision models fail with 400 "Unexpected item type in content" on DashScope #92688. It does not change or re-test external DashScope account/network behavior, and the submitted change keeps that transport/auth path unchanged.

Tests and validation

Which commands did you run?

env DASHSCOPE_API_KEY=qwen-test pnpm exec tsx -e '<resolveImageModelConfigForTool probe for qwen/qwen3.7-max with input [text,image]>'

configured active model: qwen/qwen3.7-max
configured provider metadata: qwen3.7-max declares input [text,image]
resolved image model primary: qwen/qwen-vl-max-latest
PASS: qwen3.7-max was not selected for image understanding; Qwen vision default was selected.

env DASHSCOPE_API_KEY=qwen-test pnpm exec tsx -e '<image tool probe for Qwen media understanding routing>'

tool result text: qwen image ok
image tool describeImageWithModel call: {"provider":"qwen","model":"qwen-vl-max-latest","prompt":"Describe the image.","mime":"image/png"}
PASS: image tool invoked Qwen media understanding with qwen-vl-max-latest instead of qwen3.7-max.

pnpm exec tsx -e '<manifest-backed resolveDefaultMediaModel probe for qwen3.7-max with input [text,image]>'

resolved manifest-backed default: qwen-vl-max-latest
PASS: manifest-backed Qwen default resolver skipped qwen3.7-max and selected qwen-vl-max-latest.

pnpm exec vitest run \
  src/media-understanding/defaults.test.ts \
  src/media-understanding/provider-registry.test.ts \
  extensions/qwen/index.test.ts

Test Files  3 passed (3)
     Tests  27 passed (27)

pnpm exec vitest run src/agents/tools/image-tool.test.ts

Test Files  2 passed (2)
     Tests  194 passed (194)

pnpm exec vitest run \
  src/agents/tools/image-tool.test.ts \
  src/agents/tools/pdf-tool.model-config.test.ts \
  src/media-understanding/config-provider-models.test.ts \
  src/media-understanding/image.test.ts

Test Files  5 passed (5)
     Tests  252 passed (252)

env OPENCLAW_VITEST_MAX_WORKERS=2 NODE_OPTIONS=--max-old-space-size=8192 OPENCLAW_VITEST_SHARD_NAME=agentic-agents-tools \
  pnpm exec vitest run --config test/vitest/vitest.agents-tools.config.ts src/agents/tools/image-tool.test.ts

Test Files  1 passed (1)
     Tests  98 passed (98)
  Duration  52.74s

pnpm lint --threads=8
pnpm tsgo:prod
pnpm check:test-types

lint completed with exit code 0
pnpm tsgo:prod completed with exit code 0
pnpm check:test-types completed with exit code 0

Earlier validation for the same submitted change also included the extension package-boundary compile/canary checks, additional boundary shards, plugin contracts, and CI artifact build after removing generated catalog artifacts from the commit.

What regression coverage was added or updated?

Coverage now locks the Qwen image-routing behavior at the resolver boundaries that can see configured model metadata: active image model resolution, configured provider vision resolution, default media model resolution with runtime metadata, manifest-backed default resolution, config-derived provider models, PDF tool model config, Qwen/DashScope prompt placement, and bundled Qwen provider registration.

What failed before this fix, if known?

The RED coverage reproduced qwen/qwen3.7-max being selected from configured [text,image] metadata. A later manifest-backed proof reproduced the static/default path selecting qwen3.7-max; after the follow-up, that same path selects qwen-vl-max-latest.

If no test was added, why not?

Regression tests were added or updated across the image tool, media-understanding defaults/metadata, config provider discovery, PDF tool model config, prompt placement, provider registry, and Qwen provider paths.

Risk checklist

Did user-visible behavior change? Yes

Did config, environment, or migration behavior change? No

Did security, auth, secrets, network, or tool execution behavior change? No

What is the highest-risk area?

Risk labels considered: compatibility and auth-provider. The highest-risk area is model selection for Qwen image understanding, because provider-owned capability facts now take precedence over overly broad configured input metadata for known text-only Qwen families.

Risk explanation: the compatibility-sensitive behavior is narrow. Qwen models matching the internal text-only family facts are filtered from image routing, while the existing Qwen image default remains the selected fallback target. The public manifest and plugin SDK contract shapes are not expanded.

How is that risk mitigated?

The same internal capability facts are consumed by the resolver paths covered in this patch, and regression tests exercise configured-model, provider-registry, manifest-backed default, image-tool, PDF-tool, prompt-placement, and bundled Qwen provider flows.

Current review state

What is the next action?

Maintainer-ready confidence: high after issue-specific resolver/image-tool proof, manifest-backed fallback proof, focused Qwen/media-understanding regression coverage, lint, and production/test type checks on the submitted head.

What is still waiting on author, maintainer, CI, or external proof?

The author-side refresh is complete for this scoped routing fix. The next step is maintainer review and CI on the refreshed head.

Which bot or reviewer comments were addressed?

• RF-001 addressed: the proof section includes terminal output from OpenClaw resolver/image-tool paths showing qwen3.7-max configured as [text,image] and qwen/qwen-vl-max-latest selected.
• RF-002 addressed: the after-fix proof demonstrates an image-tool/media-understanding invocation using qwen-vl-max-latest.
• RF-003 addressed: Qwen capability facts are no longer owned by shared core as Qwen constants, and the extension package-boundary compile/canary checks passed.
• RF-004 addressed: model-selection precedence is covered across configured provider, default, manifest-backed, image-tool, and PDF-tool entry points.
• RF-005 addressed: fallback/default selection proof shows qwen-vl-max-latest replacing qwen3.7-max for image understanding.
• RF-006 addressed: the public manifest/plugin SDK contract shape was not expanded for Qwen-specific capability overrides.
• RF-007 addressed: Qwen-specific capability facts live in the Qwen provider runtime metadata.
• RF-008 addressed: the Qwen extension no longer imports core src/** internals for capability facts.

Patch quality notes: the diff touches multiple resolver entry points because the same capability source-of-truth is consumed by defaults, configured model discovery, image runtime, image tool config, PDF tool config, provider registry inputs, and manifest-backed defaults. Covering those consumers together keeps the Qwen image-routing behavior consistent for the reported configuration path.