OpenClaw 语音控制

OpenClaw 语音控制是 OpenClaw 在 macOS 平台上的本地化语音控制集成方案。

代码仓库来源：

• GitHub：CarrotYuan/openclaw-voice-control

它提供以下功能：

• 唤醒词激活
• 本地麦克风音频采集
• 基于 FunASR / SenseVoice 的本地语音识别（ASR）
• 将识别出的文本转发至本地 OpenClaw 智能体
• macOS 系统级 TTS 语音播报
• 可选的叠加式 UI 界面
• 基于 launchd 的后台常驻行为
• 用户登录后自动启动

平台支持

• 仅限 macOS

安全警告

该技能新增了一个语音入口，而该入口未与身份绑定。

这意味着：

• 任何靠近麦克风的人员都可能触发该功能
• 通过所连接的 OpenClaw 智能体暴露的所有能力均可能被语音调用

推荐的安全实践：

• 在所连接智能体的提示词中显式添加安全约束
• 对高风险操作要求人工确认
• 避免为面向语音的智能体授予广泛的自主权限
• 对工具及所连接系统采用最小权限原则

主安装路径

请将本技能视为一个本地部署型技能，而非仅依赖提示词的辅助工具。

当该技能被安装到 OpenClaw 后：

• 所有操作应在当前已安装技能目录下、针对当前对话智能体进行
• 以声明的 GitHub 仓库为唯一可信来源
• 不得静默切换至其他本地克隆副本或已预配置的环境
• 必须确保工作区中已包含真实仓库文件（而不仅限于 SKILL.md），方可继续后续步骤

主安装指南详见仓库中的 README.md 文件。README.zh-CN.md 是配套中文指南。

标准安装路径如下：

1. 将完整仓库同步至当前已安装技能的工作区
2. 创建并激活 .venv 虚拟环境
3. 执行 pip install -e .
4. 下载或填充 SenseVoice 模型目录
5. 下载或填充 VAD 模型目录
6. 复制 .env.example 为 .env
7. 在 .env 中填写必需的变量值
8. 使用默认的 openWakeWord 路径
9. 同时运行语音服务进程与叠加 UI 进程，进行直接运行验证（direct-run validation）
10. 询问用户是否需要启用后台常驻行为与开机自启
11. 若用户确认，则执行 ./scripts/deploy_macos.sh
12. 若用户拒绝，则在 direct-run 验证完成后停止

在执行上述路径中任一影响系统的操作前，须明确告知用户即将执行的操作，并就以下事项获取用户确认：

• 将仓库拉取并检出至技能工作区
• 在仓库根目录下执行 pip install -e .
• 下载大型本地模型或唤醒词资源
• 启用后台常驻行为或 launchd 开机自启

最小命令执行路径：

# 从当前对话智能体已安装技能目录执行
git init
git remote add origin https://github.com/CarrotYuan/openclaw-voice-control.git
git fetch --depth 1 origin main
git checkout -B main FETCH_HEAD
# 必须确保工作区中已存在 scripts/、src/、config/、
# launchagents/ 和 README.md 后，才可继续
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
./.venv/bin/modelscope download --model iic/SenseVoiceSmall --local_dir models/SenseVoiceSmall
./.venv/bin/python - <<'PY'
from funasr import AutoModel
AutoModel(model='fsmn-vad', disable_update=True)
PY
cp .env.example .env
# 终端 1，从当前已安装技能工作区执行
python -m openclaw_voice_control --config config/default.yaml --env-file .env
# 终端 2，从同一工作区执行
python -m openclaw_voice_control.overlay_app --config config/default.yaml --env-file .env

只有当上述两条命令在同一已安装技能工作区中**同时运行**时，direct-run 验证才算完成。

在 direct-run 验证完成后、执行任何下一步操作前，**必须先终止该测试进程**。

这包括：

• 后台常驻部署
• 开机自启验证
• 启动另一次 direct-run 测试

若旧的 direct-run 服务与叠加 UI 进程仍在运行，两个活跃的语音运行时可能响应同一唤醒词，导致重复应答。

安装前必备条件

开始安装前，请确保以下前提条件已满足或可随时提供：

• Python 3.11 或更高版本
• 正在运行的本地 OpenClaw 服务
• OPENCLAW_TOKEN
• macOS 麦克风使用权限
• 能够下载本地 SenseVoice 与 VAD 模型目录的方式

对于默认路径，其余安装步骤通常可由 AI 或操作员完成：

• 将 .env.example 复制为 .env
• 下载 SenseVoice 模型目录
• 下载或填充 VAD 模型目录
• 首次运行时由 openWakeWord 自动下载所选预训练唤醒词模型

推荐的默认配置

默认公开路径配置如下：

• WAKEWORD_PROVIDER=openwakeword
• OPENWAKEWORD_MODEL_NAME=hey jarvis
• OPENCLAW_AGENT_ID=main
• OPENCLAW_MODEL=openclaw:main
• OPENCLAW_USER=openclaw-voice-control

除非用户明确要求其他配置，否则优先采用该路径。

默认路径变量说明

默认路径下的主要变量值如下：

• 以下变量需在 .env 中设置
  • OPENCLAW_BASE_URL
  • OPENCLAW_TOKEN
  • SENSEVOICE_MODEL_PATH
  • SENSEVOICE_VAD_MODEL_PATH
• 以下变量通常保留其文档默认值，除非用户明确要求定制
  • WAKEWORD_PROVIDER=openwakeword
  • OPENWAKEWORD_MODEL_NAME=hey jarvis
  • OPENCLAW_AGENT_ID=main
  • OPENCLAW_MODEL=openclaw:main
  • OPENCLAW_USER=openclaw-voice-control

若用户更改了 macOS TTS 语音，请首先确保该语音已在以下路径中完成下载：

• 系统设置
• 辅助功能
• 朗读内容
• 系统语音旁的 i 按钮
• 语言
• 语音

可选的 Porcupine 路径

Picovoice / Porcupine 是一个可选的备用路径，非默认路径。

仅当用户明确希望使用本地 .ppn 唤醒词模型时，才切换至此路径。

若选择该路径，需设置以下变量：

• WAKEWORD_PROVIDER=porcupine
• PICOVOICE_ACCESS_KEY
• WAKEWORD_FILE

仅当用户明确选择 Porcupine 路径时，才向其索取这些 Porcupine 特定参数。

切换 openWakeWord 唤醒词模型

如需切换默认的 openWakeWord 唤醒词，请修改：

• OPENWAKEWORD_MODEL_NAME

常见官方预训练模型示例包括：

• hey jarvis
• hey mycroft
• hey rhasspy
• alexa

这些预训练唤醒词模型将在首次使用时自动下载。

代码路径已支持动态切换 OPENWAKEWORD_MODEL_NAME，但截至目前，本仓库中仅对默认的 hey jarvis 路径完成了冒烟测试（smoke test）。

执行规则

使用本技能时，请遵循以下规则：

1. 优先使用声明的 GitHub 仓库。

   • 起始地址为 https://github.com/CarrotYuan/openclaw-voice-control.git
   • 不得仅因另一仓库外观相似就擅自替换。

2. 将部署操作严格限定在当前已安装技能工作区中。

   • 不得静默切换至其他本地克隆副本。
   • 若 GitHub 访问失败但本地已有克隆副本，须先征得用户同意再使用。

3. 不得静默复用旧有环境。

   • 不得假定已有 .venv、本地模型缓存、先前的 .env 或私有运行时可被复用。
   • 若复用缓存资产可节省时间，须先说明并获得用户许可。

4. 不得自行编造缺失值。

   • 编写 .env 时，须严格使用项目要求的确切变量名，尤其是 OPENCLAW_TOKEN。
   • 若必需变量或本地资源缺失，应立即中止并引导用户查阅权威文档来源。

5. 审慎处理密钥类信息。

   • 除非用户明确要求查看，否则不得将真实 token 或密钥打印至对话中。
   • 本项目应使用 ~/.openclaw/openclaw.json 中 gateway 配置项下的 OpenClaw token。
   • 不得将 ~/.openclaw/identity/device-auth.json 作为本项目的 token 来源。

6. 执行任何影响系统的操作前，必须获得用户确认。

   • 不得擅自拉取仓库、执行 pip install -e .、下载模型或启用 launchd 行为。
   • 须先说明操作内容，待用户确认后再继续。

7. 启用后台常驻行为前，必须获得用户确认。

   • 前台验证必须先行完成。
   • Direct-run 验证指在同一已安装技能工作区中，同时启动 python -m openclaw_voice_control --config config/default.yaml --env-file .env 与 python -m openclaw_voice_control.overlay_app --config config/default.yaml --env-file .env。
   • 仅当用户明确要求启用后台常驻行为或开机自启时，才执行 ./scripts/deploy_macos.sh。

日常维护

主要脚本：

• 部署后台运行时：./scripts/deploy_macos.sh
• 重启已安装的后台服务：./scripts/restart_service.sh
• 卸载已安装的后台服务：./scripts/uninstall_macos.sh
• 检查本地安装与环境问题：./scripts/doctor.sh

macOS 用户如偏好通过访达（Finder）执行，scripts/ 目录下也提供了双击即可运行的 .command 封装脚本。

关闭意图处理

将用户提出的关闭请求归类为以下两种意图之一：

• 临时禁用语音功能
  • 停止正在运行的 direct-run 进程，或停止已部署的后台运行时
  • 不删除技能文件夹
• 彻底删除技能
  • 移除技能文件夹本身
  • 仅当用户明确要求完全移除时才执行此操作

若用户表述模糊（例如“关掉它”或“停止语音”），应在执行前提出一个简短的澄清问题。

后台架构

标准后台启动路径为：

• launchd → host app → shell script → python

./scripts/deploy_macos.sh 会自动构建所需的 host app。

配置项概览

默认路径下必需配置的变量：

• OPENCLAW_BASE_URL
• OPENCLAW_TOKEN
• SENSEVOICE_MODEL_PATH
• SENSEVOICE_VAD_MODEL_PATH

默认路径下可选配置的变量：

• OPENCLAW_AGENT_ID
• OPENCLAW_MODEL
• OPENCLAW_USER
• WAKEWORD_PROVIDER
• OPENWAKEWORD_MODEL_NAME
• OPENWAKEWORD_MODEL_PATH

若用户明确切换至可选的 Porcupine 路径，还需额外配置：

• PICOVOICE_ACCESS_KEY
• WAKEWORD_FILE

仍保留解释器覆盖变量（仅用于故障排查，非主部署模式）：

• VOICE_CONTROL_PYTHON_BIN
• VOICE_CONTROL_OVERLAY_PYTHON_BIN

OPENWAKEWORD_THRESHOLD 仍作为调优变量存在，但属于故障排查类调整项，而非首次运行必需配置。

一般规则：机器特定的密钥与路径应置于 .env 中；唤醒词响应时机与阈值调优则通常应在 config/default.yaml 中进行。

缺失依赖项的获取方式

将仓库同步至当前已安装技能工作区后，请查阅 README.md 中以下章节：

• What Must Exist Before Setup（安装前必备条件）
• Required Variables（必需变量）
• Where To Get Each Requirement（各项依赖的获取方式）

实际来源说明：

• OPENCLAW_BASE_URL：应使用完整的 OpenClaw 聊天补全接口地址，而非仅主机和端口。本地默认配置为 http://127.0.0.1:18789/v1/chat/completions
• OPENCLAW_TOKEN：从 ~/.openclaw/openclaw.json 中 gateway 配置项下获取
• 默认唤醒词路径：使用 openWakeWord 及其内置英文模型 hey jarvis
• 可选 Porcupine 路径：PICOVOICE_ACCESS_KEY 与本地 .ppn 文件需从 Picovoice 获取
• 若 GitHub 克隆失败，应首先报告该错误，而非切换至无关的本地目录

相关文件

• 克隆仓库中的 README.md
• 克隆仓库中的 README.zh-CN.md
• 克隆仓库中的 docs/macos-install.md