Bug: OpenAI-compatible audio transcription fails with request Content-Type isn't multipart/form-data on Node 24

TL;DR

On Node 24.15.0 + OpenClaw 2026.4.15, any audio transcription request routed through transcribeOpenAiCompatibleAudio (Groq, OpenAI, Mistral voxtral, Moonshot, Qwen — anything that ends up in src/media-understanding/openai-compatible-audio.ts) reliably fails with HTTP 400:

Audio transcription failed (HTTP 400): {"error":{"message":"request Content-Type isn't multipart/form-data","type":"invalid_request_error"}}

The FormData body is constructed correctly, but gets stringified by the time it reaches the wire. Root cause is a cross-realm FormData / dispatcher mismatch between Node's built-in undici (bundled with Node 24) and OpenClaw's own [email protected].

Environment

• OS: Windows 10 (19045)
• Node: v24.15.0
• OpenClaw: 2026.4.15 (installed from npm)
• undici bundled inside openclaw/node_modules: 8.0.2
• Node 24's built-in undici: older (~6.x)

Reproducer

1. Install OpenClaw, configure a Groq API key (GROQ_API_KEY), and leave tools.media.audio unset so transcription falls back to the provider path.
2. Run:

openclaw infer audio transcribe --file ./any.wav --model "groq/whisper-large-v3-turbo" --language en --json

Result:

Error: Audio transcription failed (HTTP 400): {"error":{"message":"request Content-Type isn't multipart/form-data","type":"invalid_request_error"}}

This hits the OpenAI-compatible audio path via extensions/groq/media-understanding-provider.ts → transcribeOpenAiCompatibleAudio (src/media-understanding/openai-compatible-audio.ts).

Root cause

The transcription code is correct on its own:

// src/media-understanding/openai-compatible-audio.ts
const form = new FormData();                // <-- uses Node global FormData
form.append("file", blob, fileName);
form.append("model", model);
// ...
const { response } = await postTranscriptionRequest({
  url, headers, body: form, timeoutMs, fetchFn, pinDns: false,
  allowPrivateNetwork, dispatcherPolicy,
});

This flows into fetchWithSsrFGuard (src/media-understanding/shared.ts → fetch-guard infra), which then builds:

const init = { ...currentInit, redirect: "manual", ...(dispatcher ? { dispatcher } : {}), ...(signal ? { signal } : {}) };
const supportsDispatcherInit =
  params.fetchImpl !== undefined && !isAmbientGlobalFetch({ fetchImpl: params.fetchImpl, globalFetch: globalThis.fetch })
  || isMockedFetch(defaultFetch);
const response = Boolean(dispatcher) && !supportsDispatcherInit
  ? await fetchWithRuntimeDispatcher(parsedUrl.toString(), init)     // <-- normalizes FormData across undici realms
  : await defaultFetch(parsedUrl.toString(), init);                  // <-- does NOT normalize

fetchWithRuntimeDispatcher (in src/infra/net/runtime-fetch.ts) is the only path that calls normalizeRuntimeRequestInit, which re-materialises the FormData in the bundled undici's realm and strips stale content-type/content-length. The defaultFetch branch skips that entirely.

Instrumented trace

I patched fetch-guard to log init right before the branching decision. For a Groq transcription call the trace shows:

{
  "url": "https://api.groq.com/openai/v1/audio/transcriptions",
  "hasDispatcher": true,
  "supportsDispatcherInit": true,
  "bodyTag": "FormData",
  "headers": [["authorization", "Bearer gsk_***"]]
}

So: dispatcher is set, body is a FormData, headers are clean (no content-type). supportsDispatcherInit === true, so the code takes the defaultFetch(init) branch with a dispatcher attached.

Cross-realm FormData check

// executed from within openclaw's node_modules so `require("undici")` resolves to 8.0.2
const u = require("undici");
console.log("undici version:", require("undici/package.json").version); // 8.0.2
console.log("global.FormData.name:", globalThis.FormData?.name);        // FormData
console.log("undici.FormData.name:", u.FormData.name);                  // FormData
console.log("same class:", globalThis.FormData === u.FormData);         // false
const f = new globalThis.FormData();
console.log("instance of undici(8).FormData:", f instanceof u.FormData); // false
console.log("instance of global.FormData:",   f instanceof globalThis.FormData); // true

Node 24's built-in undici and OpenClaw's bundled [email protected] define two different FormData classes. A FormData created from globalThis is not instanceof the bundled one.

When the defaultFetch(init) path runs (Node global fetch), it receives an init.dispatcher that is an instance of the bundled undici's Agent. Node's built-in fetch hands the request to that external dispatcher, and the external dispatcher (undici 8) then does its own instanceof check on init.body against its own FormData. That check returns false, so the body is serialised as a plain object / stream fallback, and the eventual HTTP request goes out with a non-multipart Content-Type. Groq correctly rejects it.

Why this is a regression now

Grepping the commit log, the past two weeks have a lot of pin-DNS / SSRF / private-network / AAC rewrites landing in src/media-understanding/* (e.g. ed356d74, 43bd5545, c159d22b, 0c0463b2, f4372613, 6ee8e194). None of them exercise the cross-realm FormData × external dispatcher combination on Node 24's native fetch, which is why this slipped through. The switch to Node 24 as a supported runtime is the likely trigger — Node 24 ships undici 6.x, while OpenClaw vendors undici 8.

Proposed fix

In src/media-understanding/shared.ts (the fetchWithSsrFGuard helper), any time init.body is a FormData-like and dispatcher is non-null, route through fetchWithRuntimeDispatcher unconditionally — regardless of supportsDispatcherInit. The FormData must be re-materialised in the same undici realm as the dispatcher, which normalizeRuntimeRequestInit already does.

Sketch:

const bodyIsFormData = isFormDataLike(init.body);
const mustUseRuntimeDispatcher = Boolean(dispatcher) && (bodyIsFormData || !supportsDispatcherInit);
const response = mustUseRuntimeDispatcher
  ? await fetchWithRuntimeDispatcher(parsedUrl.toString(), init)
  : await defaultFetch(parsedUrl.toString(), init);

isFormDataLike already exists in runtime-fetch.ts and uses Symbol.toStringTag === "FormData", so it works across realms.

Alternatively, transcribeOpenAiCompatibleAudio could construct its FormData via loadUndiciRuntimeDeps().FormData so the realms match up front. The guard-layer fix is more robust because the same realm mismatch can bite any future multipart POST that flows through fetchWithSsrFGuard.

Happy to open a PR with a test that exercises the Node-native-fetch + bundled-undici-dispatcher + cross-realm-FormData path.

Workaround for users

Until this is fixed, configure tools.media.audio in openclaw.json with a local CLI (e.g. whisper-cli.exe from whisper.cpp) — that bypasses the OpenAI-compatible path entirely. Voice transcription still works, just not via Groq/OpenAI remote endpoints.