How to Use OpenClaw Voice Wake

Voice Wake is OpenClaw’s wake-word layer, and the main thing to remember is that it is global. The Gateway owns a single wake-word list, any node or app UI may edit it, and changes are persisted by the Gateway and broadcast to connected clients. There are no per-node custom wake words in the current docs.

When this is the right move

Use Voice Wake when you want macOS or iOS to listen for a small set of trigger words and start the assistant flow hands-free. Do not use it as a security boundary. It is a convenience and UX feature; channel access, Gateway auth, pairing, and permissions are still the real controls.

The practical workflow

1. Decide the global trigger list. Keep it short, pronounceable, and unlikely to fire during normal conversation.
2. Edit wake words from a supported app UI. The docs say any node or app UI may edit the Gateway-owned list.
3. Confirm macOS or iOS has local Voice Wake enabled and has the required microphone/speech permissions for that platform.
4. Remember that Android currently uses manual mic flow instead of wake-word triggers, so do not debug Android as if it should match macOS behavior.
5. After changing the list, test each connected client because the Gateway broadcasts voicewake.changed events to keep everyone in sync.

Grounded command or config pattern

The protocol is simple: get the current triggers, set a list of triggers, and listen for change events.

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

voicewake.get -> { triggers: string[] }
voicewake.set { triggers: string[] } -> { triggers: string[] }
voicewake.changed { triggers: string[] }

The Gateway stores the list at ~/.openclaw/settings/voicewake.json. Triggers are normalized by trimming and dropping empty values, and empty lists fall back to defaults. The docs also state that limits are enforced for safety, including count and length caps.

Operator notes

macOS uses the global list to gate VoiceWakeRuntime triggers. iOS uses the global list for VoiceWakeManager trigger detection and can edit Wake Words in Settings through the Gateway WebSocket. Android keeps Voice Wake disabled in runtime/settings right now and relies on manual microphone capture.

Rollout approach

For use openclaw voice wake, I would make the first pass deliberately small: one owner, one machine or channel, one visible test, and one rollback path. OpenClaw features become powerful when they connect to real tools and real messages, so the safest rollout is not a giant configuration day. It is a short rehearsal that proves the docs-grounded path works in your exact workspace before you depend on it while busy.

Common mistake

The common mistake is treating the command as the whole feature. The command starts the workflow, but the surrounding state is what keeps it reliable: config validation, auth, pairing, permissions, logs, and a tiny verification step. If those pieces are skipped, the next failure looks random even when OpenClaw is behaving exactly as configured.

Maintenance rhythm

Once this is working, write down the exact command, config path, or approval decision you used. Future you will not remember the tiny detail that made the setup safe. A small note in the workspace or runbook is cheaper than rediscovering the same behavior during an outage, especially after updates or machine changes.

Safety checks

A wake word should not be a password. Anyone near the microphone can potentially say it, and false positives are part of voice UX. Keep sensitive actions behind normal OpenClaw permissions, approvals, and explicit confirmation flows. If wake detection feels noisy, reduce the trigger list rather than adding more similar phrases.

How to verify it worked

Change a trigger, watch connected clients receive the update, and test on the actual device you care about. If one device ignores the new list, check whether it is connected to the expected Gateway and whether its local Voice Wake toggle and permissions are enabled.

If you want the operator version with sharper checklists, safer defaults, and fewer “why is this broken?” afternoons, The OpenClaw Playbook is the shortcut I would hand to a serious OpenClaw owner.