OpenClaw Companion downloads speech models and voice packages at runtime. These assets execute inside local audio pipelines, so every shipped catalog entry is bound to an HTTPS source and a pinned SHA-256 hash.
| Asset | Source of truth | Runtime storage |
|---|---|---|
| Whisper GGML models | WhisperModelManager.AvailableModels |
<tray-data>\models\ |
| Piper voice archives | PiperVoiceManager.AvailableVoices |
<tray-data>\models\piper\ |
Kokoro voice packs (model .onnx + voices-*.bin) |
KokoroModelManager.AvailablePacks |
<tray-data>\models\kokoro\<pack-id>\ |
| Silero VAD ONNX model | SileroVadModelManifest |
Audio pipeline model directory |
The source catalogs contain the download URL, pinned hash, and approximate size used by the UI. Do not duplicate those values in this document.
Kokoro's G2P dictionaries are not runtime downloads: they ship inside the
Larroy.Kokoro NuGet package and land in <app>\kokoro-dict\, because they
are tied to the native kokoro.cpp version.
The download managers fail closed:
- A catalog entry without a pinned hash is rejected before download.
- Downloads use a temporary file.
- The completed file's SHA-256 is compared with the catalog.
- A mismatch deletes the partial asset and returns an error.
- Only a verified asset is moved into its final location or extracted.
Concurrent requests for the same model or voice share one single-flight download, preventing multiple writers from racing over the same temporary file.
In Voice settings, an active Kokoro download owns its picker, status and progress until its wait ends. Completing a different voice's preview cannot reset those controls, and duplicate Download clicks do not replace the active waiter. Cancellation still ends only that caller's wait, not the shared transfer. Terminal recovery restores Retry and hides progress even when a storage-backed status refresh fails, while retaining a sanitized error message.
The selected Kokoro voice pack also downloads in the background
(KokoroVoicePackPrefetcher), evaluated at tray startup and after every settings
save. It runs only when Kokoro is the TTS provider, node or voice-response TTS is
enabled, TtsKokoroAutoDownload is true, and Windows reports the connection as
unrestricted (not metered, unknown cost, roaming, over its data limit, or offline). It touches models\kokoro only after
the provider, TTS, and auto-download checks pass, and an unusable models
directory is logged as a skipped prefetch rather than interrupting tray startup.
A skipped or failed prefetch waits for the next launch or save. Deleting the pack
in Voice settings clears TtsKokoroAutoDownload so it is not fetched again;
Download sets it. Every waiter on the shared transfer receives its progress, so
Voice settings attaches to a running prefetch on load, voice selection, or a
provider/TTS change that starts one, instead of showing "not downloaded".
Settings schema v2 moves a schema v1 piper provider with no downloaded Piper
voice to Kokoro once. Setup writes settings.json without a provider, and v1
resolved that to Piper, so setup-driven installs spoke through the Windows fallback.
AssetHashPinningTests guards the catalog shape by requiring a lowercase
64-character SHA-256 and an HTTPS URL for every shipped entry.
-
Download the exact upstream artifact outside the application.
-
Verify the artifact identity and release provenance from an independent upstream source when one is available.
-
Compute the hash:
Get-FileHash .\artifact -Algorithm SHA256
-
Update the appropriate source catalog with the exact lowercase hash.
-
Run:
dotnet test .\tests\OpenClaw.Shared.Tests\OpenClaw.Shared.Tests.csproj ` --filter AssetHashPinningTests
-
Exercise one real download and confirm a deliberately incorrect hash is rejected and the temporary file is removed.
-
Record the upstream release or commit and verification evidence in the change description.
Before every public release, re-verify every shipped audio-asset hash from the published upstream artifact and record the evidence for release review.
The current catalogs are compiled into the signed application. If the catalog grows or needs out-of-band updates, replace the inline tables with a versioned, signed manifest that binds URL, size, hash, model identity, and upstream provenance. Runtime behavior must remain fail closed when the manifest or asset cannot be verified.