```

Local or self-hosted media providers that intentionally do not require

credentials can expose `resolveSyntheticAuth` and return a non-secret

marker. OpenClaw still keeps the normal auth gate for providers that do

not explicitly opt in.

credentials can expose `resolveAuth` and return `kind: "none"`.

OpenClaw still keeps the normal auth gate for providers that do not

explicitly opt in. Existing providers can keep reading `req.apiKey`;

new providers should prefer `req.auth`.

```typescript

api.registerMediaUnderstandingProvider({

id: "local-audio",

capabilities: ["audio"],

resolveSyntheticAuth: () => ({

apiKey: "custom-local",

source: "local-audio plugin synthetic auth",

mode: "api-key",

resolveAuth: () => ({

kind: "none",

source: "local-audio plugin no-auth",

}),

transcribeAudio: async (req) => ({ text: "Transcript..." }),

});

mode: "api-key" | "oauth" | "token" | "aws-sdk";

};

export type ProviderAuthErrorCode = "missing-api-key" | "missing-provider-auth";

export class ProviderAuthError extends Error {

readonly code: ProviderAuthErrorCode;

readonly provider: string;

constructor(code: ProviderAuthErrorCode, provider: string, message: string) {

super(message);

this.name = "ProviderAuthError";

this.code = code;

this.provider = provider;

}

}

export function isProviderAuthError(

err: unknown,

code?: ProviderAuthErrorCode,

): err is ProviderAuthError {

return err instanceof ProviderAuthError && (!code || err.code === code);

}

export function resolveAwsSdkEnvVarName(env: NodeJS.ProcessEnv = process.env): string | undefined {

if (env[AWS_BEARER_ENV]?.trim()) {

return AWS_BEARER_ENV;

if (key) {

return key;

}

throw new Error(formatMissingAuthError(auth, provider));

throw new ProviderAuthError("missing-api-key", provider, formatMissingAuthError(auth, provider));

}

isNonSecretApiKeyMarker,

NON_ENV_SECRETREF_MARKER,

} from "./model-auth-markers.js";

import type { ResolvedProviderAuth } from "./model-auth-runtime-shared.js";

import { ProviderAuthError, type ResolvedProviderAuth } from "./model-auth-runtime-shared.js";

import { normalizeProviderId } from "./model-selection.js";

export {

} from "./auth-profiles.js";

export {

formatMissingAuthError,

isProviderAuthError,

ProviderAuthError,

requireApiKey,

resolveAwsSdkEnvVarName,

} from "./model-auth-runtime-shared.js";

const authStorePath = resolveAuthStorePathForDisplay(agentDir);

const resolvedAgentDir = path.dirname(authStorePath);

throw new Error(

throw new ProviderAuthError(

"missing-provider-auth",

provider,

[

`No API key found for provider "${provider}".`,

`Auth store: ${authStorePath} (agentDir: ${resolvedAgentDir}).`,

import { describe, expect, it, vi } from "vitest";

import { CUSTOM_LOCAL_AUTH_MARKER } from "../agents/model-auth-markers.js";

import { VERSION } from "../version.js";

import {

createRequestCaptureJsonFetch,

expect((file as File).name).toBe("voice-note.m4a");

});

it("omits bearer auth for explicit no-auth requests", async () => {

const { fetchFn, getRequest } = createRequestCaptureJsonFetch({ text: "ok" });

await transcribeOpenAiCompatibleAudio({

buffer: Buffer.from("audio"),

fileName: "note.mp3",

apiKey: CUSTOM_LOCAL_AUTH_MARKER,

auth: { kind: "none", source: "local provider" },

timeoutMs: 1000,

fetchFn,

provider: "local-audio",

baseUrl: "https://audio.example.com/v1",

defaultBaseUrl: "https://audio.example.com/v1",

defaultModel: "whisper-local",

});

const headers = new Headers(getRequest().init?.headers);

expect(headers.get("authorization")).toBeNull();

});

it("uses typed api-key auth for bearer headers", async () => {

const { fetchFn, getRequest } = createRequestCaptureJsonFetch({ text: "ok" });

await transcribeOpenAiCompatibleAudio({

buffer: Buffer.from("audio"),

fileName: "note.mp3",

apiKey: "legacy-key",

auth: { kind: "api-key", apiKey: "typed-key", source: "test" },

timeoutMs: 1000,

fetchFn,

provider: "local-audio",

baseUrl: "https://audio.example.com/v1",

defaultBaseUrl: "https://audio.example.com/v1",

defaultModel: "whisper-local",

});

const headers = new Headers(getRequest().init?.headers);

expect(headers.get("authorization")).toBe("Bearer typed-key");

});

it("wraps malformed transcription JSON with a stable provider error", async () => {

const fetchFn = vi.fn<typeof fetch>().mockResolvedValueOnce(new Response("{ nope"));

params: OpenAiCompatibleAudioParams,

): Promise<AudioTranscriptionResult> {

const fetchFn = params.fetchFn ?? fetch;

const apiKey = params.auth?.kind === "api-key" ? params.auth.apiKey : params.apiKey;

const defaultHeaders =

params.auth?.kind === "none" || !apiKey

? undefined

: {

authorization: `Bearer ${apiKey}`,

};

const { baseUrl, allowPrivateNetwork, headers, dispatcherPolicy } =

resolveProviderHttpRequestConfig({

baseUrl: params.baseUrl,

defaultBaseUrl: params.defaultBaseUrl,

headers: params.headers,

request: params.request,

defaultHeaders: {

authorization: `Bearer ${params.apiKey}`,

},

defaultHeaders,

provider: params.provider,

api: "openai-audio-transcriptions",

capability: "audio",