OpenClaw Voice Wake 설정하기

음성 인식 기능을 개발하다 보면 디바이스마다 호출어(Wake Word) 설정을 따로 관리해야 해서 번거로울 때가 많아요. 폰에서는 잘 작동하는데 노트북에서는 반응하지 않거나, 기기마다 다른 단어를 설정해야 한다면 관리 포인트가 늘어나고 사용자 경험도 파편화되죠. OpenClaw는 이런 문제를 해결하기 위해 호출어를 한곳에서 관리하는 방식을 사용합니다.

What You’ll Need

• OpenClaw Gateway
• 연결된 Node (macOS, iOS 또는 Android)

Quick Start

OpenClaw에서 호출어는 Gateway가 소유한 단일 글로벌 리스트로 처리됩니다. Node별로 커스텀 호출어를 따로 두지 않기 때문에 관리가 훨씬 편해요.

1. 저장 위치 확인

호출어 데이터는 Gateway 호스트의 아래 경로에 JSON 형식으로 저장됩니다.

• ~/.openclaw/settings/voicewake.json

데이터 구조 예시:

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

2. Protocol 및 API 사용

어떤 Node나 앱 UI에서도 이 리스트를 수정할 수 있고, 변경 사항은 Gateway를 통해 연결된 모든 기기에 브로드캐스트됩니다.

• voicewake.get: 현재 설정된 { triggers: string[] } 리스트를 가져옵니다.
• voicewake.set: 새로운 { triggers: string[] } 리스트를 설정합니다.
• voicewake.changed: 리스트가 변경되면 모든 WebSocket 클라이언트와 연결된 Node에 이 이벤트가 전달됩니다.

Client Behavior

각 플랫폼은 글로벌 리스트를 받아와서 다음과 같이 동작합니다.

1. macOS app: 글로벌 리스트를 기반으로 VoiceWakeRuntime 트리거를 제어합니다. 앱 내에서 단어를 수정하면 즉시 voicewake.set을 호출합니다.
2. iOS node: VoiceWakeManager를 통해 호출어를 감지합니다. 설정에서 변경하면 Gateway WS를 통해 동기화됩니다.
3. Android node: 설정 메뉴에 호출어 편집기가 내장되어 있습니다. 여기서 수정하면 모든 곳에 변경 사항이 반영됩니다.
4. WebSocket Clients: WebChat 같은 클라이언트도 초기 연결 시 현재 상태를 전달받고, 변경 이벤트가 발생할 때마다 실시간으로 업데이트됩니다.

Troubleshooting

• 호출어 리스트를 비웠을 때: 리스트가 비어 있으면 시스템 기본값(Defaults)이 자동으로 적용됩니다.
• 입력한 단어가 저장되지 않을 때: 안전을 위해 호출어의 개수와 길이에 제한(Limits)이 걸려 있습니다. 너무 긴 단어나 너무 많은 단어를 추가했는지 확인해 보세요.
• 특정 기기에서만 반응하지 않을 때: 호출어 리스트는 글로벌로 공유되지만, 각 디바이스마다 Voice Wake 활성화/비활성화 토글 스위치가 따로 있습니다. 해당 기기의 로컬 설정과 권한을 확인해야 합니다.

더 궁금한 점이 있다면 AI Setup Assistant에게 질문해 보세요.

What’s Next

• Gateway API Reference
• Node Configuration Guide