核心用法
mlx-whisper 是为 OpenClaw 设计的本地语音转文字技能，专为 Apple Silicon（M1/M2/M3/M4）Mac 优化。当用户通过 Telegram 或 WhatsApp 发送语音消息时，该技能自动将音频文件（.ogg 或 .opus 格式）转录为文本，供 Agent 后续处理。整个过程无需调用任何云端 API，完全依赖本地计算。
安装流程包含三步：首先通过 pip3 install mlx-whisper 安装核心库；其次将包装脚本 mlx-whisper-transcribe.sh 部署至 Python 用户目录的 bin 文件夹；最后在 ~/.openclaw/openclaw.json 中配置 tools.media.audio 模块，指定 CLI 命令路径与超时参数。首次运行时会自动下载约 465MB 的 whisper-small-mlx 模型，后续完全离线运行。
配置支持灵活定制：可切换 tiny/small/medium/large-v3 四种模型规格，也可在 args 中追加语言代码（如 "zh"、"en"）以跳过自动检测、加速转录。建议根据精度需求与存储空间权衡选择模型。
显著优点
1. 极致隐私：语音数据全程本地处理，不上传任何第三方服务器，适合对数据敏感的个人或企业场景。
2. 性能飞跃：基于苹果 MLX 机器学习框架深度优化，在 M 系列芯片上比标准 Whisper 快约 60 倍，1 分钟音频约 7 秒完成转录。
3. 零 API 成本：无需申请 OpenAI API Key 或按量付费，一次性配置后永久免费使用。
4. 即时可用：安装完成后完全离线运行，无网络环境亦可正常工作。
潜在缺点与局限性
1. 平台锁定：仅限 macOS Apple Silicon 设备，Intel Mac 及 Windows/Linux 用户无法使用。
2. 首次下载依赖：虽运行期离线，但初次需联网下载模型文件（75MB–3GB），对网络环境有临时要求。
3. 存储占用：默认 small 模型 465MB，若选用 large-v3 则达 3GB，对磁盘空间有限的设备构成压力。
4. 非音乐识别：Whisper 专为语音设计，无法转录纯音乐或含强烈背景噪音的音频。
5. 配置门槛：需用户熟悉命令行操作、Python 环境管理及 JSON 配置编辑，非技术用户上手成本较高。
适合的目标群体
- 隐私敏感型用户：律师、医生、记者等需确保语音内容不外泄的专业人士。
- Apple Silicon Mac 用户：已配备 M 系列芯片且希望充分利用 NPU/GPU 算力的开发者或效率工具爱好者。
- OpenClaw 重度使用者：频繁通过 Telegram/WhatsApp 与 Agent 语音交互，希望降低延迟与成本的用户。
- 离线场景需求者：经常在无网络环境（如飞机上、偏远地区）使用语音输入的用户。
使用风险
1. 模型下载失败：首次配置时若网络中断，可能导致模型不完整，需手动清理 ~/.cache/huggingface 后重试。
2. 超时风险：长音频（如 30 分钟以上）可能触发默认 60 秒超时，需在配置中适当调大 timeoutSeconds。
3. Python 环境冲突：若系统存在多版本 Python 或虚拟环境，可能导致 mlx_whisper 模块导入失败，建议明确使用 python3 与 pip3。
4. 脚本权限问题：忘记执行 chmod +x 会导致 OpenClaw 调用失败，需确保包装脚本具备可执行权限。
5. 语言识别偏差：未指定语言时，自动检测可能误判小语种或口音浓重的录音，建议明确传入语言参数以提升准确率。