The OpenClaw openai-whisper skill helps an agent turn an audio file on its execution machine into text or subtitles without an OpenAI API key. Start with a short Chinese recording you are allowed to process: produce an original-language TXT file on CPU with base, then choose SRT or a separate English translation. The installation commands below target a macOS execution machine with Homebrew. A remote Gateway or container needs its own dependencies and an accessible audio path.
There are two versions here: ClawHub skill 1.0.0 supplies the instructions; OpenAI Whisper CLI 20250625 processes the audio. Inference is local, while installation and the first download of a selected model need network access. Treat the result as a draft to review. This workflow does not provide speaker diarization or guarantee real-time speed or word-for-word accuracy.
Check the skill, then prepare its execution machine
Replace YOUR_AGENT_ID with your target agent. In an OpenClaw CLI terminal, inspect the selected Gateway’s inventory and prerequisites:
openclaw skills info openai-whisper --agent YOUR_AGENT_ID
openclaw skills check --agent YOUR_AGENT_ID
If the bundled skill is present, prepare the CLI. Consider installing the registry package only when the skill is actually missing:
openclaw skills install @steipete/openai-whisper --version 1.0.0 --agent YOUR_AGENT_ID
The registry package still uses legacy metadata.clawdbot; current OpenClaw ignores its dependency gates and installer hints. The current bundled version uses metadata.openclaw. A ready-looking registry entry therefore does not establish that all dependencies exist. Following this guide does not require reinstalling or overriding an existing bundled copy.
On the macOS machine that will run Whisper, install the CLI if it is missing:
brew install openai-whisper
The current stable Homebrew formula uses 20250625 revision 7 and manages dependencies including FFmpeg, Python and PyTorch. Check the command in that same execution environment:
command -v whisper
whisper --help
ffmpeg -version
brew info openai-whisper
Confirm that whisper resolves to the intended installation and exposes the options used below. Homebrew manages its own Python and dependency environment. You do not need to replace its managed Python to match the upstream README’s expected 3.8–3.11 range. Metadata from an arbitrary system Python does not describe this executable.
Finding Whisper on the Gateway host does not make it available inside a sandbox. A container also needs Whisper, FFmpeg, readable audio, writable output and a usable model cache. After installing dependencies, start a new session and check readiness again. Prepare the execution environment instead of disabling its sandbox.
First recording: save original-language TXT
Choose a short recording and replace the path with a real file accessible to the execution machine. This command explicitly selects multilingual base, Chinese speech, transcription and CPU:
whisper "/absolute/path/sample.m4a" --model base --language Chinese --task transcribe --device cpu --fp16 False --output_format txt --output_dir "./whisper-output/original"
--language identifies the spoken language, rather than a desired output language. Do not choose English-only base.en for Chinese audio. CPU is a straightforward way to check the workflow; time and memory needs still depend on your machine and recording. The CLI chooses CUDA by default when available, otherwise CPU. It does not automatically select an Apple GPU.
Alternatively, adapt this request in your OpenClaw conversation:
Use the openai-whisper skill to transcribe /absolute/path/sample.m4a.
Keep the Chinese speech in Chinese. First check that the execution environment can read the audio, has whisper and ffmpeg, and has no same-named old output in the destination.
Use base, CPU and fp16 False. Save TXT to ./whisper-output/original.
If a model download is needed, tell me its name and cache location first. Report the actual output path and flag material I should verify by listening.
This request limits the task; execution and downloading still depend on your agent’s permissions and environment.
The first use of base downloads its weights. The usual cache is ~/.cache/whisper; when XDG_CACHE_HOME is set, Whisper uses its whisper subdirectory. To choose a location, append --model_dir "/absolute/path/whisper-models" to the command. It must be writable. A valid cached copy is reused for the same model and environment, but another user, container or model may need a new download. Local inference does not mean that an initial run is offline.
Check completion and produce subtitles
For this example, look for ./whisper-output/original/sample.txt: Whisper derives the output name from the audio basename without its extension. Confirm it was created by this run, open it, and listen back to names, numbers, specialist terms, quiet sections and the ending. A generated file establishes an output to review, rather than transcript accuracy.
The CLI catches some per-file errors, prints Skipping … and continues. A finished command or exit code alone cannot confirm that the recording was transcribed. Check the error messages and this run’s output; an old file can otherwise look like success.
For original-language subtitles, run:
whisper "/absolute/path/sample.m4a" --model base --language Chinese --task transcribe --device cpu --fp16 False --output_format srt --output_dir "./whisper-output/subtitles"
Check sample.srt for numbered cues, start/end timestamps and text, then review timing in a subtitle player. TXT lacks that subtitle timing structure. Without --output_format, the CLI defaults to producing TXT, VTT, SRT, TSV and JSON. Choosing one format makes a first run easier to inspect.
Whisper overwrites an existing output with the same basename and format. Two sample.m4a files from different directories, or an original transcript and translation of one recording, can overwrite each other if sent to the same destination. Use separate output directories or distinct input filenames.
English translation: select a model and a separate destination
--task translate translates speech into English. It does not select arbitrary target languages. The default turbo model was not trained for translation; the skill’s short translation example leaves the model unspecified, so copying it can produce the original language. This command explicitly uses the multilingual medium model from the official README’s translation example and a different directory:
whisper "/absolute/path/sample.m4a" --model medium --language Chinese --task translate --device cpu --fp16 False --output_format srt --output_dir "./whisper-output/english"
This is another transcription job. The first use of medium downloads its own weights and can require more resources than base. Verify that the output is English and check meaning and timing. For other target languages, obtain the original transcript first and use an appropriate text-translation workflow.
Troubleshoot the observed problem
- Missing command or FFmpeg decoder error: inspect PATH and dependencies in the agent’s actual execution environment. Your terminal, Gateway, remote node and container can differ. For
Failed to load audio, read the underlying FFmpeg error and confirm the path and file are readable. - Model download or cache failure: check the selected model, network access, disk space and cache permissions. An invalid checksum triggers a fresh download. An explicit
--model_dirhelps make the intended cache location clear. - CPU FP16 warning: version 20250625 switches to FP32; this guide sets
--fp16 Falseexplicitly. That warning alone does not mean transcription failed. - Slow processing, exhausted memory or incorrect text: verify the workflow with a short recording and a smaller multilingual model before adjusting it. The README’s relative speeds were measured on an A100 and do not predict your computer’s completion time. Wrong language selection, noise, hallucinated words and repetition require checking against the audio.
Keep the original output when editing a transcript or writing a summary. For multiple-speaker labels, live streams or a fuller video-caption editing task, choose a workflow that supports those requirements.
If a cloud transcription workflow suits your task better, see the API-based transcribe guide.