OpenClaw 语音唤醒词自定义教程

2026-01-27 · 6 分钟进阶玩法

概述

语音唤醒词（Voice Wake）让你可以通过说出特定关键词来激活 OpenClaw，无需手动操作界面。本文将介绍唤醒词的配置管理、多客户端同步以及各平台的实现差异。

唤醒词配置文件

唤醒词由 Gateway 全局管理，配置存储在：

~/.openclaw/settings/voicewake.json

默认配置内容：

{
  "triggers": [
    "openclaw",
    "claude",
    "computer"
  ]
}

这三个是预设的默认唤醒词，你可以根据需要自定义。

管理唤醒词

查看当前唤醒词

通过 API 获取当前配置的所有唤醒词：

# 使用 voicewake.get 接口
curl http://127.0.0.1:18789/api/voicewake/get

返回示例：

{
  "triggers": ["openclaw", "claude", "computer"]
}

设置新唤醒词

使用 voicewake.set 接口更新唤醒词列表：

curl -X POST http://127.0.0.1:18789/api/voicewake/set \
  -H "Content-Type: application/json" \
  -d '{"triggers": ["小爪", "助手", "openclaw"]}'

直接编辑配置文件

你也可以直接修改 JSON 文件：

{
  "triggers": [
    "小爪",
    "助手",
    "openclaw",
    "你好"
  ]
}

修改后保存，Gateway 会自动检测变更并重新加载。

多客户端广播同步

当唤醒词发生变更时，Gateway 通过 voicewake.changed 事件广播通知所有已连接的客户端：

Gateway 更新唤醒词
       │
       ├──> 广播 voicewake.changed
       │
       ├──> macOS 客户端（更新本地唤醒引擎）
       ├──> iOS 客户端（更新唤醒监听器）
       └──> Android 客户端（更新编辑器配置）

所有客户端会实时同步最新的唤醒词列表，无需手动刷新。

各平台实现

macOS - VoiceWakeRuntime

macOS 平台使用 VoiceWakeRuntime 引擎实现唤醒检测：

基于系统原生语音识别框架
在后台持续运行，资源占用低
支持中英文混合唤醒词

iOS - VoiceWakeManager

iOS 平台通过 VoiceWakeManager 管理唤醒功能：

利用 iOS 语音框架进行本地识别
遵循 iOS 后台运行限制
支持锁屏状态下的唤醒

Android - 编辑器集成

Android 平台将唤醒功能集成在编辑器组件中：

与输入法协同工作
支持自定义唤醒灵敏度

安全限制

为防止滥用，唤醒词系统设有安全限制：

数量限制

// 唤醒词数量不能超过系统上限
{
  "triggers": [
    // 建议控制在 5-8 个以内
    // 过多的唤醒词会增加误触发概率
  ]
}

长度限制

每个唤醒词有最小和最大字符长度限制：

太短的词（如单个字）容易误触发
太长的短语不利于语音识别

建议唤醒词长度在 2-6 个汉字或 4-12 个英文字母之间。

唤醒词选择建议

选择好的唤醒词需要考虑以下因素：

辨识度高：避免日常对话中频繁出现的词语
发音清晰：选择音节分明、不易混淆的词
便于记忆：团队使用时确保所有成员都能记住
多语言兼容：如果使用中英文混合环境

{
  "triggers": [
    "小爪同学",
    "openclaw"
  ]
}

高级配置

结合 Talk 模式

唤醒词通常与 Talk 语音对话模式配合使用：

// ~/.openclaw/openclaw.json
{
  "talk": {
    "enabled": true,
    "voiceWake": {
      "enabled": true,
      "sensitivity": 0.7  // 唤醒灵敏度
    }
  }
}

调试唤醒检测

开启调试日志查看唤醒词匹配详情：

{
  "logging": {
    "voiceWake": "debug"
  }
}

日志中会显示每次检测到的候选词和匹配置信度。

故障排查

唤醒词无响应？

确认 voicewake.json 文件格式正确
检查麦克风权限是否已授予
验证 Talk 模式是否已启用

频繁误触发？

更换为辨识度更高的唤醒词
减少唤醒词数量
降低唤醒灵敏度

多设备不同步？

检查所有客户端是否连接到同一个 Gateway
查看 Gateway 日志确认 voicewake.changed 事件是否正常广播