Voice wake (macOS)

기준일: 2026-07-26
공식 기준: Voice wake (macOS)

Voice wake (macOS) 문서는 OpenClaw 공식 문서(platforms/mac/voicewake)를 한국어로 정리한 가이드입니다. Voice wake and push-to-talk modes plus routing details in the mac app 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Voice wake and push-to-talk modes plus routing details in the mac app

한국어 가이드 범위: platforms/mac/voicewake 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Voice Wake & Push-to-Talk
요구사항
Modes
Runtime behavior (wake-word)
Lifecycle invariants
Push-to-talk specifics
User-facing settings
Forwarding behavior
Forwarding payload
Quick verification
관련 문서

상세 내용

Voice Wake & Push-to-Talk

이 섹션의 세부 항목은 공식 문서 Voice Wake & Push-to-Talk를 참고하세요.

요구사항

Voice Wake and push-to-talk require macOS 26 or newer. On older macOS the controls are hidden from the Voice settings page, which shows the macOS 26 requirement instead.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Modes

주요 항목:

Wake-word mode (default): an always-on, on-device Speech recognizer waits for trigger tokens (swabbleTriggerWords). On match it starts capture, shows the overlay with partial text, and auto-sends after silence.
Push-to-talk (hold Right Option): hold the right Option key to capture immediately, no trigger needed. The overlay appears while held; releasing finalizes and forwards after a short delay so you can edit the text.

Runtime behavior (wake-word)

주요 항목:

The recognizer lives in VoiceWakeRuntime.
Trigger fires only when there is a meaningful pause between the wake word and the next word (triggerPauseWindow = 0.55s). The overlay/chime can start on the pause even before the command begins.
Silence windows: 2.0s (silenceWindow) when speech is flowing, 5.0s (triggerOnlySilenceWindow) if only the trigger was heard.
Hard stop: 120s (captureHardStop) to prevent runaway sessions.
Debounce between sessions: 350ms (debounceAfterSend) after a send.
The overlay is driven via VoiceWakeOverlayController, with committed/volatile text coloring.
After send, the recognizer restarts cleanly to listen for the next trigger.

Lifecycle invariants

주요 항목:

If Voice Wake is enabled and permissions are granted, the wake-word recognizer stays listening, except during an active push-to-talk capture.
Overlay dismissal, including manual dismiss via the X button, always resumes the recognizer: VoiceSessionCoordinator.overlayDidDismiss calls VoiceWakeRuntime.refresh(state:) on every dismiss path. See Voice overlay for the session/token model.

Push-to-talk specifics

주요 항목:

Hotkey detection uses a global .flagsChanged monitor for right Option (keyCode 61 + .option). It only observes events, never swallows them.
Capture lives in VoicePushToTalk: starts Speech immediately, streams partials to the overlay, and calls VoiceWakeForwarder on release.
Starting push-to-talk pauses the wake-word runtime to avoid dueling audio taps; it restarts automatically after release.
Permissions: requires Microphone + Speech; receiving key events needs Accessibility/Input Monitoring approval.
External keyboards: some do not expose right Option as expected. Offer a fallback shortcut if users report misses.

User-facing settings

주요 항목:

Voice Wake toggle: enables the wake-word runtime.
Hold Right Option to talk: enables the push-to-talk monitor.
If the selected language lacks on-device recognition on this Mac, Voice Wake stays disabled while push-to-talk and Talk Mode remain available.
Language and mic pickers, a live level meter, a trigger-word table, and a tester (local-only, never forwards).
The mic picker preserves the last selection if a device disconnects, shows a disconnected hint, and temporarily falls back to the system default until it returns.
Sounds: chimes on trigger detect and on send, defaulting to the macOS "Glass" system sound. Pick any NSSound-loadable file (e.g. MP3/WAV/AIFF) per event, or choose No Sound.

Forwarding behavior

주요 항목:

On forward, VoiceWakeForwarder.selectedSessionOptions picks the active WebChat session key if one is set, otherwise the gateway's main session key.
It looks up that session via sessions.list and derives the delivery channel and target from the session's delivery context (falling back to its last channel/target, then to a parsed session key), defaulting to WebChat if nothing resolves.
If delivery fails, the error is logged (voicewake.forward category) and the run is still visible via WebChat/session logs.

Forwarding payload

주요 항목:

VoiceWakeForwarder.prefixedTranscript(_:) prepends a machine-hint line (resolved host name, falling back to "this Mac") before the transcript, shared between wake-word and push-to-talk paths.

Quick verification

주요 항목:

Toggle push-to-talk on, hold Right Option, speak, release: overlay should show partials then send.
While holding, the menu-bar ears should stay enlarged (triggerVoiceEars(ttl: nil)); they drop after release.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/mac/voicewake
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Voice wake (macOS)

기준일: 2026-07-26
공식 기준: Voice wake (macOS)

핵심 요약

Voice wake and push-to-talk modes plus routing details in the mac app

한국어 가이드 범위: platforms/mac/voicewake 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Voice Wake & Push-to-Talk
요구사항
Modes
Runtime behavior (wake-word)
Lifecycle invariants
Push-to-talk specifics
User-facing settings
Forwarding behavior
Forwarding payload
Quick verification
관련 문서

상세 내용

Voice Wake & Push-to-Talk

이 섹션의 세부 항목은 공식 문서 Voice Wake & Push-to-Talk를 참고하세요.

요구사항

Voice Wake and push-to-talk require macOS 26 or newer. On older macOS the controls are hidden from the Voice settings page, which shows the macOS 26 requirement instead.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Modes

주요 항목:

Wake-word mode (default): an always-on, on-device Speech recognizer waits for trigger tokens (swabbleTriggerWords). On match it starts capture, shows the overlay with partial text, and auto-sends after silence.
Push-to-talk (hold Right Option): hold the right Option key to capture immediately, no trigger needed. The overlay appears while held; releasing finalizes and forwards after a short delay so you can edit the text.

Runtime behavior (wake-word)

주요 항목:

The recognizer lives in VoiceWakeRuntime.
Trigger fires only when there is a meaningful pause between the wake word and the next word (triggerPauseWindow = 0.55s). The overlay/chime can start on the pause even before the command begins.
Silence windows: 2.0s (silenceWindow) when speech is flowing, 5.0s (triggerOnlySilenceWindow) if only the trigger was heard.
Hard stop: 120s (captureHardStop) to prevent runaway sessions.
Debounce between sessions: 350ms (debounceAfterSend) after a send.
The overlay is driven via VoiceWakeOverlayController, with committed/volatile text coloring.
After send, the recognizer restarts cleanly to listen for the next trigger.

Lifecycle invariants

주요 항목:

If Voice Wake is enabled and permissions are granted, the wake-word recognizer stays listening, except during an active push-to-talk capture.
Overlay dismissal, including manual dismiss via the X button, always resumes the recognizer: VoiceSessionCoordinator.overlayDidDismiss calls VoiceWakeRuntime.refresh(state:) on every dismiss path. See Voice overlay for the session/token model.

Push-to-talk specifics

주요 항목:

Hotkey detection uses a global .flagsChanged monitor for right Option (keyCode 61 + .option). It only observes events, never swallows them.
Capture lives in VoicePushToTalk: starts Speech immediately, streams partials to the overlay, and calls VoiceWakeForwarder on release.
Starting push-to-talk pauses the wake-word runtime to avoid dueling audio taps; it restarts automatically after release.
Permissions: requires Microphone + Speech; receiving key events needs Accessibility/Input Monitoring approval.
External keyboards: some do not expose right Option as expected. Offer a fallback shortcut if users report misses.

User-facing settings

주요 항목:

Voice Wake toggle: enables the wake-word runtime.
Hold Right Option to talk: enables the push-to-talk monitor.
If the selected language lacks on-device recognition on this Mac, Voice Wake stays disabled while push-to-talk and Talk Mode remain available.
Language and mic pickers, a live level meter, a trigger-word table, and a tester (local-only, never forwards).
The mic picker preserves the last selection if a device disconnects, shows a disconnected hint, and temporarily falls back to the system default until it returns.
Sounds: chimes on trigger detect and on send, defaulting to the macOS "Glass" system sound. Pick any NSSound-loadable file (e.g. MP3/WAV/AIFF) per event, or choose No Sound.

Forwarding behavior

주요 항목:

On forward, VoiceWakeForwarder.selectedSessionOptions picks the active WebChat session key if one is set, otherwise the gateway's main session key.
It looks up that session via sessions.list and derives the delivery channel and target from the session's delivery context (falling back to its last channel/target, then to a parsed session key), defaulting to WebChat if nothing resolves.
If delivery fails, the error is logged (voicewake.forward category) and the run is still visible via WebChat/session logs.

Forwarding payload

주요 항목:

VoiceWakeForwarder.prefixedTranscript(_:) prepends a machine-hint line (resolved host name, falling back to "this Mac") before the transcript, shared between wake-word and push-to-talk paths.

Quick verification

주요 항목:

Toggle push-to-talk on, hold Right Option, speak, release: overlay should show partials then send.
While holding, the menu-bar ears should stay enlarged (triggerVoiceEars(ttl: nil)); they drop after release.

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/platforms/mac/voicewake
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

Voice wake (macOS)

핵심 요약

문서 구성

상세 내용

Voice Wake & Push-to-Talk

요구사항

Modes

Runtime behavior (wake-word)

Lifecycle invariants

Push-to-talk specifics

User-facing settings

Forwarding behavior

Forwarding payload

Quick verification

관련 문서

실습 체크리스트

관련 링크

관련 가이드

Voice wake (macOS)

핵심 요약

문서 구성

상세 내용

Voice Wake & Push-to-Talk

요구사항

Modes

Runtime behavior (wake-word)

Lifecycle invariants

Push-to-talk specifics

User-facing settings

Forwarding behavior

Forwarding payload

Quick verification

관련 문서

실습 체크리스트

관련 링크

관련 가이드