OpenClaw Voice Control

---

name: openclaw-voice-control

description: Local macOS voice-control integration for OpenClaw. Use when setting up, deploying, troubleshooting, or operating wakeword-triggered voice access to a local OpenClaw agent with ASR, TTS, overlay UI, and launchd background support.

homepage: https://github.com/CarrotYuan/openclaw-voice-control

metadata: {"openclaw":{"os":["darwin"],"homepage":"https://github.com/CarrotYuan/openclaw-voice-control","requires":{"bins":["python3","git","launchctl"],"env":["OPENCLAW_BASE_URL","OPENCLAW_TOKEN","SENSEVOICE_MODEL_PATH","SENSEVOICE_VAD_MODEL_PATH"]},"primaryEnv":"OPENCLAW_TOKEN"}}

---

# OpenClaw Voice Control

OpenClaw Voice Control is a local macOS voice-control integration for OpenClaw.

Repository source:

It provides:

Platform

Safety Warning

This skill adds a voice entrypoint, and that entrypoint is not identity-bound.

That means:

Recommended safety practice:

Main Path

Treat this as a local deployment skill, not as a prompt-only helper.

When this skill is installed into OpenClaw:

The main installation guide is the repository `README.md`.

`README.zh-CN.md` is the Chinese companion guide.

Use this as the standard install path:

1. sync the full repository into the current installed skill workspace

2. create and activate `.venv`

3. run `pip install -e .`

4. download or populate the SenseVoice model directory

5. download or populate the VAD model directory

6. copy `.env.example` to `.env`

7. fill the required values in `.env`

8. use the default openWakeWord route

9. run direct-run validation with both the voice service and overlay process

10. ask whether the user wants background resident behavior and auto-start

11. if yes, run `./scripts/deploy_macos.sh`

12. if no, stop after direct-run validation

Before running any system-changing step in that path, explicitly tell the user

what you are about to do and get confirmation for:

Minimum command path:

# from the current conversation agent's installed skill directory
git init
git remote add origin https://github.com/CarrotYuan/openclaw-voice-control.git
git fetch --depth 1 origin main
git checkout -B main FETCH_HEAD
# do not continue until the workspace contains scripts/, src/, config/,
# launchagents/, and README.md
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
./.venv/bin/modelscope download --model iic/SenseVoiceSmall --local_dir models/SenseVoiceSmall
./.venv/bin/python - <<'PY'
from funasr import AutoModel
AutoModel(model='fsmn-vad', disable_update=True)
PY
cp .env.example .env
# terminal 1, from the current installed skill workspace
python -m openclaw_voice_control --config config/default.yaml --env-file .env
# terminal 2, from the same workspace
python -m openclaw_voice_control.overlay_app --config config/default.yaml --env-file .env

Direct-run validation is not complete unless both commands above are running at

the same time from the same installed skill workspace.

Before any next step after direct-run validation, stop that test

first.

This includes:

If an old direct-run service and overlay are left running, two active voice

runtimes can respond to the same wakeword and produce duplicate replies.

What Must Exist Before Setup

Before setup begins, make sure these prerequisites exist or can be provided:

For the default route, the remaining setup can usually be handled by the AI or

operator:

Recommended Defaults

The default public route is:

Prefer that route unless the user explicitly asks for something else.

Default Route Variables

These are the main values for the default route:

- `OPENCLAW_BASE_URL`

- `OPENCLAW_TOKEN`

- `SENSEVOICE_MODEL_PATH`

- `SENSEVOICE_VAD_MODEL_PATH`

- `WAKEWORD_PROVIDER=openwakeword`

- `OPENWAKEWORD_MODEL_NAME=hey jarvis`

- `OPENCLAW_AGENT_ID=main`

- `OPENCLAW_MODEL=openclaw:main`

- `OPENCLAW_USER=openclaw-voice-control`

If the user changes the macOS TTS voice, first make sure that voice has been

downloaded in:

Optional Porcupine Route

Picovoice / Porcupine is an optional fallback route, not the default path.

Only switch to it when the user explicitly wants to use a local `.ppn` wakeword

model.

If that route is chosen, set:

Only ask for those Porcupine-specific values when the user explicitly chooses

that route.

Switching openWakeWord Models

To switch the default openWakeWord wakeword, change:

Common official pretrained examples include:

Those pretrained wakeword models are downloaded automatically on first use.

The code path already supports changing `OPENWAKEWORD_MODEL_NAME`, but only the

default `hey jarvis` route has been smoke-tested in this repository so far.

Execution Rules

When using this skill, follow these rules:

1. Use the declared GitHub repository first.

- Start from `https://github.com/CarrotYuan/openclaw-voice-control.git`

- Do not substitute another repository just because it looks similar.

2. Keep deployment work in the current installed skill workspace.

- Do not silently switch to another local clone.

- If GitHub access fails and a local clone exists, ask before using it.

3. Do not silently reuse an old environment.

- Do not assume an existing `.venv`, local model cache, previous `.env`, or private runtime should be reused.

- If reusing cached assets might save time, explain that and ask first.

4. Do not invent missing values.

- When writing `.env`, use the exact variable names required by the project, especially `OPENCLAW_TOKEN`.

- If required values or local assets are missing, stop and point to the documented source of truth.

5. Handle secrets conservatively.

- Do not print real tokens or keys back into the conversation unless the user explicitly asks to see them.

- For this project, use the OpenClaw token from `~/.openclaw/openclaw.json`, specifically the `gateway` configuration.

- Do not use `~/.openclaw/identity/device-auth.json` as the token source for this project.

6. Ask before any system-changing action.

- Do not assume you should fetch the repository, run `pip install -e .`, download models, or enable launchd behavior without user approval.

- Explain the action first, then continue only after the user confirms.

7. Ask before enabling background resident behavior.

- Foreground validation comes first.

- Direct-run validation means starting both `python -m openclaw_voice_control --config config/default.yaml --env-file .env` and `python -m openclaw_voice_control.overlay_app --config config/default.yaml --env-file .env` from the same installed skill workspace.

- Only run `./scripts/deploy_macos.sh` when the user explicitly wants background resident behavior or auto-start.

Daily Maintenance

Primary scripts:

Double-click `.command` wrappers are also available in `scripts/` for macOS users who prefer Finder-based execution.

Shutdown Intents

Treat shutdown requests as one of these two user intents:

- stop the running direct-run process, or stop the deployed background runtime

- do not delete the skill folder

- remove the skill folder itself

- only do this when the user explicitly asks for full removal

If the user says something ambiguous like "turn it off" or "stop voice", ask one short clarification question before acting.

Background Architecture

The canonical background startup path is:

`./scripts/deploy_macos.sh` builds the required host apps automatically.

Configuration Surface

Default-route required values:

Default-route configurable values:

If the user explicitly switches to the optional Porcupine route, also configure:

Interpreter override variables still exist:

They are troubleshooting knobs only, not the main deployment model.

`OPENWAKEWORD_THRESHOLD` still exists as a tuning variable, but it is a

troubleshooting adjustment rather than a first-run requirement.

As a rule, machine-specific secrets and paths belong in `.env`, while wakeword

timing and threshold tuning should normally be adjusted in `config/default.yaml`.

Where To Get Missing Requirements

After syncing the repository into the current installed skill workspace, read these sections in `README.md`:

Practical source notes:

Related Files