Voice overlay
기준일: 2026-07-26
공식 기준: Voice overlay
Voice overlay 문서는 OpenClaw 공식 문서(platforms/mac/voice-overlay)를 한국어로 정리한 가이드입니다. Voice overlay lifecycle when wake-word and push-to-talk overlap 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.
핵심 요약
Voice overlay lifecycle when wake-word and push-to-talk overlap
한국어 가이드 범위: platforms/mac/voice-overlay 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.
문서 구성
공식 문서의 주요 섹션은 다음과 같습니다.
- Voice Overlay Lifecycle (macOS)
- 동작
- Implementation
- Logging
- Debugging checklist
- 관련 문서
상세 내용
Voice Overlay Lifecycle (macOS)
Audience: macOS app contributors. Goal: keep the voice overlay predictable when wake-word and push-to-talk overlap.
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
동작
주요 항목:
- If the overlay is already visible from wake-word and the user presses the hotkey, the hotkey session adopts the existing text instead of resetting it. The overlay stays up while the hotkey is held. On release: send if there is trimmed text, otherwise dismiss.
- Wake-word alone still auto-sends on silence; push-to-talk sends immediately on release.
Implementation
주요 항목:
VoiceSessionCoordinator(apps/macos/Sources/OpenClaw/VoiceSessionCoordinator.swift) is the single owner of the active voice session. It is a@MainActor @Observablesingleton, not an actor. API:startSession,updatePartial,finalize,sendNow,dismiss,updateLevel,snapshot. Each session carries aUUIDtoken; calls with a stale or mismatched token are dropped.VoiceWakeOverlayController(VoiceWakeOverlayController+Session.swift) renders the overlay and forwards user actions (requestSend,dismiss) back through the coordinator via the session token. It never owns the session state itself.- Push-to-talk (
VoicePushToTalk.begin()) adopts any visible overlay text asadoptedPrefix(viaVoiceSessionCoordinator.shared.snapshot()) so pressing the hotkey while the wake overlay is up keeps the text and appends new speech. On release, it waits up to 1.5s for a final transcript before falling back to the current text. - On
dismiss, the overlay callsVoiceSessionCoordinator.overlayDidDismiss, which triggersVoiceWakeRuntime.refresh(state:)so manual X-dismiss, empty-text dismiss, and post-send dismiss all resume wake-word listening. - Unified send path: if trimmed text is empty, dismiss; otherwise
sendNowplays the send chime once, forwards viaVoiceWakeForwarder, then dismisses.
Logging
Voice subsystem is ai.openclaw; each component logs under its own category:
위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과
--help를 확인하세요.
| Category | Component |
|---|---|
voicewake.coordinator |
VoiceSessionCoordinator |
voicewake.overlay |
VoiceWakeOverlayController/VoiceWakeOverlay |
voicewake.ptt |
Push-to-talk hotkey and capture |
voicewake.runtime |
Wake-word runtime |
voicewake.chime |
Chime playback |
voicewake.sync |
Global settings sync |
voicewake.forward |
Transcript forwarding |
voicewake.meter |
Mic level monitor |
Debugging checklist
주요 항목:
- Stream logs while reproducing a sticky overlay:
- Verify only one active session token; stale callbacks are dropped by the coordinator.
- Confirm push-to-talk release always calls
end()with the active token; if text is empty, expect a dismiss without chime or send.
sudo log stream --predicate 'subsystem == "ai.openclaw" AND category CONTAINS "voicewake"' --level info --style compact
관련 문서
주요 항목:
- macOS app
- Voice wake (macOS)
- Talk mode
실습 체크리스트
- 공식 문서와 로컬 버전을 대조합니다:
https://docs.openclaw.ai/platforms/mac/voice-overlay - 관련 CLI는
openclaw --help및 하위 명령--help로 옵션을 확인합니다. - 설정 변경 시
openclaw config/openclaw doctor로 유효성을 검사합니다. - Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.
자주 쓰는 명령·설정 예시
sudo log stream --predicate 'subsystem == "ai.openclaw" AND category CONTAINS "voicewake"' --level info --style compact
관련 링크
이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.