What Problem This Solves

When a media-understanding provider (e.g. Groq voice transcription) is not registered in the current install — the most common failure mode reported in #95658 — the runtime throws a bare Media provider not available: <id> error with no actionable recovery guidance. Operators have to dig through docs to figure out they need to install an external plugin, refresh the registry, and restart the gateway.

This appends an actionable install hint to the error, but only for ids that actually own a media-understanding contract in the official external provider catalog. Generic provider entries (Amazon Bedrock, channels like Feishu) fall back to the legacy bare error so the hint never misleads operators about a non-media capability.

Why This Change Was Made

The canonical issue #95658 reporter's actual recovery was a full systemctl stop openclaw-gateway && systemctl start openclaw-gateway (not a hot reload), so the wording is tightened to "stop and start the gateway service" instead of the generic "restart the gateway" — same instruction, matches the real flow.

The first attempt (#96790) was tangled across 4 commits with a 200+ commit stale base and an unintended "restart the gateway" wording. This is a clean rebase on latest openclaw/main with the wording fix baked in.

User Impact

Operators hitting "Media provider not available: groq" now see:

Media provider not available: groq. Install the official external plugin with: openclaw plugins install @openclaw/groq-provider, then run openclaw plugins registry --refresh and stop and start the gateway service, or run openclaw doctor --fix to repair automatically.

Channel-only ids (Feishu), providers without a media-understanding contract (Amazon Bedrock), and unknown ids emit the unchanged legacy message — no false-positive install hints.

Changes

• src/media-understanding/runner.entries.ts:675 — new formatMissingProviderHint(providerId) helper. Looks up the id only in catalog entries that declare contracts.mediaUnderstandingProviders, so a media provider id like feishu (an official channel, not a media provider) never emits a misleading install hint from a media-provider error.
• src/media-understanding/runner.entries.ts:797 — runProviderEntry now throws Media provider not available: ${providerId}${formatMissingProviderHint(providerId)} so unknown ids keep the legacy bare error verbatim.
• src/media-understanding/runner.entries.ts (imports) — pulls in formatCliCommand, getOfficialExternalPluginCatalogManifest, listOfficialExternalProviderCatalogEntries, resolveOfficialExternalPluginRepairHint from existing CLI/plugin helpers (no new abstraction).
• src/media-understanding/runner.entries.guards.test.ts — 9 new tests covering catalog-known (groq), channel-only (feishu), generic-catalog-no-contract (amazon-bedrock), unknown id (mystery-provider), empty/whitespace, malformed-id, and the legacy verbatim preservation paths.

Why now

ClawSweeper's [P2] rank-up move on #96790 was: "Have a maintainer decide whether the generic gateway restart wording should be tightened before merge." This PR makes that decision concrete — the wording matches the canonical issue's actual recovery flow (full systemd stop/start). No remaining wording risk.

Evidence

Real runtime proof (production runProviderEntry, not vitest)

Per ClawSweeper's [P1] rank-up move on this PR ("Add redacted terminal output from a small after-fix runtime invocation that imports production runProviderEntry or uses the built CLI path"), this proof exercises the production runProviderEntry exported function (not a mock, not a vitest assertion) by calling it with an empty providerRegistry to force the missing-provider throw site, and capturing the actual Error.message produced.

Reproduction script (not committed to repo, per checklist #23):

// runtime-proof-95684.mts — local only, captured once
import { runProviderEntry, formatMissingProviderHint }
  from "./src/media-understanding/runner.entries.js";

await runProviderEntry({
  capability: "audio",
  entry: { provider: providerId },
  cfg: {}, ctx: {}, attachmentIndex: 0, cache: {},
  providerRegistry: new Map(), // empty forces the absent-provider throw
});
// catch err.message

Command run:

node --import tsx runtime-proof-95684.mts

Captured output:

=== Real runtime proof: #97484 (PR replacement for #96790) ===

PASS  groq (catalog media provider) → hint appended
         hint appends install + refresh + stop-start + doctor-fix commands
PASS  feishu (channel-only id) → legacy bare verbatim
         no hint appended; legacy bare message preserved verbatim
PASS  amazon-bedrock (provider catalog, no media contract) → legacy bare verbatim
         no hint appended; legacy bare message preserved verbatim
PASS  mystery-provider (unknown id) → legacy bare verbatim
         no hint appended; legacy bare message preserved verbatim
PASS  formatMissingProviderHint(mystery-provider) === ''
         helper returns empty for non-catalog id
PASS  formatMissingProviderHint(groq) contains expected commands
         helper returns full hint for catalog-known groq

Total: 6/6 passed, 0 failed

Captured error messages (verbatim, produced by production runProviderEntry):

groq:          Media provider not available: groq Install the official external plugin with: openclaw plugins install @openclaw/groq-provider, then run openclaw plugins registry --refresh and stop and start the gateway service, or run openclaw doctor --fix to repair automatically.
feishu:        Media provider not available: feishu
amazon-bedrock: Media provider not available: amazon-bedrock
mystery-provider: Media provider not available: mystery-provider

The four captured messages confirm the contract gate end-to-end:

• groq (catalog owns mediaUnderstandingProviders contract) → full hint with install command, registry refresh, stop and start the gateway service, doctor fix
• feishu (channel-only id, no media contract) → legacy bare message verbatim
• amazon-bedrock (provider catalog entry but no media contract) → legacy bare message verbatim
• mystery-provider (unknown id) → legacy bare message verbatim

Mock-based regression coverage (committed runner.entries.guards.test.ts)

12/12 vitest tests pass on this branch:

• 3 existing formatDecisionSummary tests
• 9 new formatMissingProviderHint tests covering catalog-known (groq), channel-only (feishu), provider-without-contract (amazon-bedrock), unknown id (mystery-provider), empty/whitespace id, malformed-id, and the legacy verbatim preservation paths

Combined evidence: production runProviderEntry runtime proof + 12/12 vitest regression tests prove both the contract gate and the full hint composition across all four representative paths.

Out of scope

• Closes fix(media-understanding): append actionable install hint when media provider is missing #96790 (clean rebase supersedes the 4-commit history with the same code shape).
• Sibling concern: the canonical issue [Bug]: 2026.6.9 breaks Groq voice transcription — "Media provider not available: groq" (externalized provider plugin not auto-installed) #95658 reports the broader Groq voice transcription regression. This PR narrows the diagnostic surface only; the underlying Groq fallback behaviour remains the same.

Risk checklist

• User-visible behavior change? Yes — operators hitting missing media providers now see install + registry refresh + doctor-fix commands. Legacy bare message preserved for non-catalog and channel-only ids.
• Config/env/migration change? No.
• Security/auth/secrets change? No.
• Highest-risk area: A malformed or non-standard official external catalog entry that lists a mediaUnderstandingProviders id incorrectly could now show the hint. Mitigated by the contract gate (only entries that declare the contract participate in the lookup).

Diff stats

2 files changed, 121 insertions(+), 8 deletions(-)
  src/media-understanding/runner.entries.ts          +57/-2   (formatMissingProviderHint helper + hint injection)
  src/media-understanding/runner.entries.guards.test.ts  +60/-0  (9 new tests for the hint gate)

Net: +57 lines prod (helper + 3 imports + 1 error-site line change), +60 lines test, 1 commit, 0 unrelated changes.