用 OpenClaw 的 openai-whisper Skill，可以把执行机上的音频转成原语言文字或字幕，不需要 OpenAI API key。本指南从一段你有权处理的短中文录音开始，先用 CPU 和 base 模型生成 TXT，再说明如何单独生成 SRT 或英语译文。安装命令面向已有 Homebrew 的 macOS 执行机；远程 Gateway 或容器需要在实际执行环境准备依赖和可访问的音频路径。
这里区分两种版本：ClawHub Skill 为 1.0.0，负责告诉 Agent 怎样调用工具；真正处理音频的是 OpenAI Whisper CLI 20250625。模型推理在本地完成，安装和首次下载所选模型仍需要网络。它适合先做可检查的转录草稿；本流程不提供说话人标注，也不承诺实时速度或逐字准确。
先检查 Skill，再准备执行机
把 YOUR_AGENT_ID 换成实际目标 Agent，在 OpenClaw CLI 所在终端检查选定 Gateway 的库存与条件：
openclaw skills info openai-whisper --agent YOUR_AGENT_ID
openclaw skills check --agent YOUR_AGENT_ID
已有内置 Skill 时，继续准备 CLI；只有确实缺少该 Skill 才考虑安装上架版：
openclaw skills install @steipete/openai-whisper --version 1.0.0 --agent YOUR_AGENT_ID
上架版仍使用旧 metadata.clawdbot，当前 OpenClaw 不读取其中的依赖门槛和安装提示；当前内置版本已使用 metadata.openclaw。因此不能仅凭上架版显示可用就断言依赖齐全，也不需要为了跟这篇指南重复安装或覆盖已有内置版本。
在实际运行 Whisper 的 macOS 机器上，如尚未安装 CLI：
brew install openai-whisper
当前稳定 Homebrew Formula 指向 20250625 revision 7，并管理 FFmpeg、Python 和 PyTorch 等依赖。随后在同一执行环境检查入口：
command -v whisper
whisper --help
ffmpeg -version
brew info openai-whisper
先确认 whisper 指向预期安装，并能看到下面使用的参数。Homebrew 管理自己的 Python 和依赖环境；无需按上游 README 的 Python 3.8–3.11 预期范围手动替换它的受管 Python。任意系统 Python 的 pip 信息也不能代表这个命令。
Gateway 主机能找到 whisper，也不代表沙盒里能找到它。若任务在容器中执行，容器也必须有 Whisper、FFmpeg、可读音频、可写输出及模型缓存目录。安装新依赖后开启新会话，重新检查条件；不要通过关闭沙盒来替代环境准备。
第一段录音：保存原语言 TXT
先挑一段短录音，将路径换成执行机能读到的真实文件。下面命令显式选择多语言 base 模型、中文、原语言转写和 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 表示音频中说的语言，不是想要的输出语言；中文录音不要选英语专用的 base.en。CPU 方式便于先确认流程可用，耗时和内存仍取决于录音与机器。CLI 默认在 CUDA 可用时选 CUDA，否则选 CPU；这不表示 Apple GPU 会自动启用。
也可以在 OpenClaw 对话中这样提出任务，改好路径后发送：
用 openai-whisper Skill 转写 /absolute/path/sample.m4a。
保留中文，不做翻译。先确认实际执行环境能读取音频，whisper 和 ffmpeg 可用，输出目录没有同名旧稿。
使用 base、CPU、fp16 False，输出 TXT 到 ./whisper-output/original。
若需要下载模型，先告诉我模型名称和缓存位置；完成后报告实际文件路径，并指出需要人工听回核对的内容。
这段输入用于限定一次任务，具体是否执行和下载仍由你的 Agent 权限与环境决定。
第一次使用 base 会下载其权重。默认缓存通常是 ~/.cache/whisper；设置了 XDG_CACHE_HOME 时则使用该目录下的 whisper。需要指定缓存位置，可在同一命令追加 --model_dir "/absolute/path/whisper-models"。该目录必须可写；以后同一环境、同一模型且缓存校验成功时会复用已有文件。不同执行用户、容器或模型可能再次下载，不能把“本地推理”理解成第一次运行一定离线。
怎样确认完成，以及改成字幕
以上示例应写入 ./whisper-output/original/sample.txt：输出取音频文件名并去掉扩展名。确认文件是这次生成的，再打开内容；对照原音频听回人名、数字、专有词、安静段和结尾。出现文件只是转换完成的线索，内容仍需检查。
CLI 会捕获某些逐文件错误，打印 Skipping … 后继续；因此仅看命令结束或退出码不足以确认音频已转好。查找错误信息与本次输出，避免把已有旧文件当成成功结果。
要生成原语言字幕，用同一录音运行以下命令：
whisper "/absolute/path/sample.m4a" --model base --language Chinese --task transcribe --device cpu --fp16 False --output_format srt --output_dir "./whisper-output/subtitles"
检查 sample.srt 中是否有字幕序号、开始与结束时间以及文本，再用字幕播放器核对时序。TXT 没有这些字幕时间结构。省略 --output_format 会默认输出 TXT、VTT、SRT、TSV、JSON 多种格式；第一次只选所需格式更容易检查。
Whisper 会覆盖输出目录中同 basename、同格式的文件。不同目录的两个 sample.m4a，或同一录音的原文与译文，写进同一个输出目录时可能互相覆盖；为它们选不同目录或先改文件名。
需要英语译文时，明确更换模型和目录
--task translate 是把语音译成英语，不用于任意目标语言。默认模型 turbo 没有训练翻译任务；Skill 的简短翻译示例没有指定模型，照抄可能仍得到原语言。下面明确使用官方 README 英译示例中的多语言 medium，并另存目录：
whisper "/absolute/path/sample.m4a" --model medium --language Chinese --task translate --device cpu --fp16 False --output_format srt --output_dir "./whisper-output/english"
这是另一次转录任务，第一次使用 medium 也需要下载它自己的权重，并可能比 base 占用更多资源。核对输出确实是英语，同时检查含义和时序。要其他目标语言，先取得原语言稿，再用适合的文本翻译流程处理。
卡住时按现象检查
- 找不到命令或 FFmpeg 解码失败： 在 Agent 实际执行环境检查 PATH 和依赖；终端能运行不等于 Gateway、远程节点或容器也能运行。
Failed to load audio时看随后的 FFmpeg 原始错误，并确认路径与文件可读。 - 下载或缓存失败： 核对所选模型、网络、磁盘空间和缓存写权限。校验失败的文件会触发重新下载；使用明确的
--model_dir可减少对缓存位置的误判。 - CPU 显示 FP16 警告： 20250625 会改用 FP32；本指南显式设置
--fp16 False。这条警告本身不等于转录失败。 - 慢、内存不足或文本不对： 先用短音频和较小多语言模型确认流程，再调整模型。不要套用 README 在 A100 上的相对速度预测自己电脑的耗时；错误语言、噪音、幻觉和重复文本都需要听回原音频处理。
需要整理转录稿后再写摘要，可保留原始输出另做编辑。若任务需要多人说话人标注、实时流或更完整的视频字幕编辑，应另选支持该任务的流程。
如果更适合使用云端转录流程，可以继续查看调用 API 的 transcribe 指南。