PR #62266: fix(image): keep tool available for vision-capable runtime models

• Repository: openclaw/openclaw
• Author: BlackishGreen33
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/62266

Description (problem / solution / changelog)

Summary

• Problem: when agents.defaults.imageModel is not set, runs using opencode-go/minimax-m2.7 can lose the image tool even though the active runtime model already has vision support.
• Why it matters: if the image tool is missing, agents can only guess from text instead of analyzing the uploaded image.
• What changed: createImageTool() now falls back to the active runtime model only when the run already proved the model is vision-capable, and the tool wiring now passes both modelProvider and modelId down to that fallback.
• What did NOT change (scope boundary): this does not change provider alias rules, does not change the existing MiniMax or Z.ai config-driven fallback logic, and does not change config schema.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #61789
• Related #61789
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: tool registration only used config-level image model inference. When resolveImageModelConfigForTool() returned null for opencode-go/minimax-m2.7, createImageTool() returned null immediately, even if the active runtime model was already known to support vision.
• Missing detection / guardrail: there was no regression test for the case where config-driven fallback is unavailable but the active runtime model is already vision-capable, and there was no top-level tool registration test covering that wiring.
• Contributing context (if known): createOpenClawTools() already knew the active provider, but it did not pass the active model id through to createImageTool(), so the runtime-only fallback path was not available from the normal coding-tool assembly path.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/tools/image-tool.test.ts, src/agents/openclaw-tools.image-generation.test.ts
• Scenario the test should lock in: keep config-driven fallback disabled for opencode-go/minimax-*, but still register the image tool when the active runtime model is confirmed vision-capable and the runtime provider/model id are available.
• Why this is the smallest reliable guardrail: the bug happens while building the tool list, so one focused createImageTool() regression test plus one createOpenClawTools() registration test cover the exact failure boundary without needing a live provider.
• Existing test that already covers this (if any): the existing image-tool suite already covers the explicit config path and the MiniMax / MiniMax Portal / Z.ai config-driven pairing behavior.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• Agents using a vision-capable runtime model like opencode-go/minimax-m2.7 keep the image tool available even when agents.defaults.imageModel is not explicitly set.
• Existing explicit agents.defaults.imageModel behavior stays the same.

Diagram (if applicable)

Before:
[vision-capable runtime model] -> [config-driven image fallback returns null] -> [image tool omitted]

After:
[vision-capable runtime model] -> [config-driven image fallback returns null] -> [runtime model fallback] -> [image tool registered]

Security Impact (required)

• New permissions/capabilities? (Yes/No): No
• Secrets/tokens handling changed? (Yes/No): No
• New/changed network calls? (Yes/No): No
• Command/tool execution surface changed? (Yes/No): No
• Data access scope changed? (Yes/No): No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS
• Runtime/container: Node 22.14.0 via fnm
• Model/provider: opencode-go/minimax-m2.7
• Integration/channel (if any): N/A
• Relevant config (redacted): agents.defaults.model.primary=opencode-go/minimax-m2.7, with no explicit agents.defaults.imageModel

Steps

1. Configure the primary model as opencode-go/minimax-m2.7 without setting agents.defaults.imageModel.
2. Build the agent tool list for a run where the active runtime model is already marked modelHasVision: true.
3. Inspect whether the image tool is registered.

Expected

• The image tool stays available because the active runtime model is already known to support vision.

Actual

• Before this fix, createImageTool() returned null and the top-level tool list omitted image.
• After this fix, the tool stays registered when the runtime model is vision-capable, while still staying disabled if vision support is not confirmed.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

• Verified scenarios: ran fnm exec --using 22.14.0 pnpm test -- src/agents/tools/image-tool.test.ts src/agents/openclaw-tools.image-generation.test.ts and confirmed the new runtime-fallback regression cases plus the top-level createOpenClawTools() registration path.
• Edge cases checked: the runtime fallback still stays off when modelHasVision is not confirmed, and the existing config-driven MiniMax / MiniMax Portal / Z.ai cases remained green in the same image-tool test file.
• What you did not verify: a live opencode-go run, a full green pnpm check, or a full pnpm test run.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No): Yes
• Config/env changes? (Yes/No): No
• Migration needed? (Yes/No): No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: the image tool could become available for a runtime model that is mislabeled as vision-capable.
  • Mitigation: the new fallback only activates when modelHasVision === true and both runtime modelProvider and modelId are present; otherwise behavior stays unchanged.
• Risk: local repo-wide verification is currently blocked by unrelated latest-main TypeScript failures in extensions/acpx/src/runtime.ts and extensions/acpx/src/runtime.test.ts.
  • Mitigation: this PR stays scoped to the image tool wiring and regression tests, and the targeted Node 22 test coverage above directly exercises the changed behavior.

Changed files

• src/agents/openclaw-tools.image-generation.test.ts (modified, +50/-0)
• src/agents/openclaw-tools.ts (modified, +4/-2)
• src/agents/tools/image-tool.test.ts (modified, +81/-0)
• src/agents/tools/image-tool.ts (modified, +17/-2)