Hermes语音集成

Step 1 — Install Hermes Agent

Install Hermes using the official installer:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Restart your shell, then verify:

hermes --version
hermes doctor

Run the setup wizard if this is your first Hermes install:

hermes setup

Choose a model/provider. For a local-first HA assistant, configure Hermes to use your local model endpoint (for example Ollama, vLLM, or llama.cpp). Remote providers also work.

---

Step 3 — Install the Hermes plugins

Clone this repository:

mkdir -p ~/dev
cd ~/dev
git clone https://github.com/rusty4444/hermes-voice-ha-integration.git
cd hermes-voice-ha-integration

Copy the plugins into your Hermes plugin directory:

mkdir -p ~/.hermes/plugins
cp -R plugins/home_assistant ~/.hermes/plugins/home_assistant
cp -R plugins/voice_stack ~/.hermes/plugins/voice_stack

Configure Home Assistant connection details for Hermes. The plugin reads standard environment variables:

```bash cat >> ~/.hermes/.env <<'EOF'

Step 4 — Test Hermes ↔ Home Assistant before installing anything in HA

Start Hermes:

hermes

Ask:

Search my Home Assistant lights.

Then try a read-only state check:

Is the living room light on?

Expected result:

• Hermes should use ha_search_entities or ha_get_state.
• The response should include the current state from Home Assistant.
• If Home Assistant is unreachable, Hermes should say that it cannot reach HA rather than crashing.

If this fails, skip ahead to Troubleshooting before enabling write actions.

---

Step 5 — Install the Home Assistant custom integration

Option B — Manual install

From this repo checkout, copy the custom component into HA's config directory:

cp -R custom_components/hermes /config/custom_components/hermes

If you are copying over SSH/Samba from another machine, the target is the Home Assistant config directory:

/config/custom_components/hermes

Restart Home Assistant after copying.

---

Development setup

cd ~/dev/hermes-voice-ha-integration
python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
python -m pytest tests/ -q

Run static compilation:

python -m compileall -q custom_components plugins tests

Build package metadata:

python -m build --sdist --wheel

Run release integrity checks:

python scripts/check_release_integrity.py

See docs/release.md for the full release checklist and artifact semantics.

The tests are mocked and do not require a live Home Assistant instance.

---

Optional: bearer token for the HA-to-Hermes WebSocket connection. Leave empty if no auth is needed.

HERMES_HA_WS_TOKEN= EOF

**About the `HASS_URL` format:** The URL must include a scheme (`http://` or `https://`) and a hostname or IP address. For example `http://192.168.1.50:8123`. If you see `"No host part in the URL"`, the URL is missing the `http://` prefix or the hostname.

**About `HERMES_HA_WS_TOKEN`:** This is optional and used to secure the connection **from Home Assistant to Hermes**. Most users do not need it:

- **Leave empty** (or omit) for unauthenticated WebSocket connections.
- **Set to any string** (e.g. `my-hermes-token`) if you want to require a matching token on the HA side. If you set this, enter the same value in the HA custom integration setup form field "Hermes API / WebSocket token".
- If unset, the system falls back to `API_SERVER_KEY` or `HERMES_API_KEY` if either is configured.

If your HA URL is different, use that instead, for example:

Enable the plugins in `~/.hermes/config.yaml`:

If your config already has a `plugins.enabled` list, add the two entries instead of replacing the whole section.

Restart Hermes after changing plugins or `.env`.

**How the WebSocket receiver starts:** The WebSocket receiver does not require a standalone `server.py` file. It starts automatically when the `voice_stack` plugin loads. After restarting Hermes, check that the WebSocket is active:

Option A — HACS custom repository

1. In Home Assistant, open HACS.
2. Open the three-dot menu → Custom repositories.
3. Add this repository URL:

   https://github.com/rusty4444/hermes-voice-ha-integration
   

1. Choose category Integration.
2. Install Hermes Voice Assistant.
3. Restart Home Assistant.

Step 7 — Configure the voice pipeline via the HA options UI

After adding the integration, open Settings → Devices &amp; services → Hermes Voice Assistant → Options.

The options flow has two pages.

Step 9 — Configure safety controls

The plugin blocks dangerous service domains by default, including:

• shell_command
• command_line
• python_script
• pyscript
• hassio
• rest_command

For extra safety, create an allow-list at:

~/.hermes/ha_allow_list.json

Example:

{
  "enabled": true,
  "rules": [
    {"entity_id": "light.*", "services": ["turn_on", "turn_off", "toggle"]},
    {"entity_id": "scene.*", "services": ["turn_on"]},
    {"entity_id": "media_player.living_room", "services": ["play_media", "volume_set"]}
  ]
}

When enabled, service calls not matching the allow-list are denied.

Audit logs are written as JSON lines to:

~/.hermes/ha_audit.log

---

Step 10 — Optional: fine-tune voice engines outside HA

Install optional voice dependencies in the Python environment that runs Hermes.

TTS options

Edge TTS (easy, network-backed)

pip install edge-tts

Configure:

cat >> ~/.hermes/.env <<'EOF'
HERMES_TTS_ENGINE=edge
HERMES_TTS_VOICE=en-US-AriaNeural
EOF

Piper TTS (offline)

pip install piper-tts

Download a Piper voice model from:

https://huggingface.co/rhasspy/piper-voices

Configure:

cat >> ~/.hermes/.env <<'EOF'
HERMES_TTS_ENGINE=piper
HERMES_TTS_VOICE=en_US-lessac-medium
EOF

STT options

faster-whisper

pip install faster-whisper sounddevice numpy

Configure:

cat >> ~/.hermes/.env <<'EOF'
HERMES_STT_ENGINE=faster-whisper
HERMES_STT_MODEL=tiny
EOF

Wake-word options

Porcupine

pip install pvporcupine pyaudio

Create a Picovoice key, then add:

cat >> ~/.hermes/.env <<'EOF'
HERMES_WAKE_WORD_ENGINE=porcupine
HERMES_WAKE_WORD=computer
PORCUPINE_ACCESS_KEY=replace-with-picovoice-key
EOF

OpenWakeWord

pip install openwakeword pyaudio numpy

Configure:

cat >> ~/.hermes/.env <<'EOF'
HERMES_WAKE_WORD_ENGINE=openwakeword
EOF

Step 11 — Optional Home Assistant add-on

This repository includes an early HA add-on scaffold in addon/. Use it if you want Hermes voice services to run under Home Assistant Supervisor instead of a separate machine.

High-level flow:

1. Add this repository as an add-on repository in Settings → Add-ons → Add-on Store → Repositories.
2. Install Hermes Voice Assistant.
3. Configure model/STT/TTS/wake-word settings in the add-on options.
4. Start the add-on.
5. Open the add-on logs and confirm Hermes starts cleanly.

The add-on is intentionally marked boot: manual in v0.0.5. Start it manually first, verify logs, then decide whether to change boot behaviour later.

---

Test the WebSocket endpoint (replace with your Hermes host/port)

curl -N --no-buffer -H "Accept: text/event-stream" http://localhost:7860/api/hermes/ws

The `voice_stack` plugin starts a small HA-facing WebSocket receiver at:

Home Assistant connects to this endpoint through the Hermes URL you enter below. If HERMES_HA_WS_TOKEN, API_SERVER_KEY, or HERMES_API_KEY is set, the HA custom integration token must match it.

---

Hermes × Home Assistant Voice Integration

<p align="center"> <a href="https://buymeacoffee.com/rusty4" target="_blank"> <img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" height="50"> </a> </p>

Connect Hermes Agent to Home Assistant so Hermes can understand your home, call HA services, and optionally run a wake-word → STT → LLM → TTS voice loop.

This repository is a bundle of three pieces:

The Python wheel is intentionally plugin-focused. Use the GitHub tag or source distribution for the full HACS/custom-component/add-on bundle.

Release: v0.0.5 — ships runtime Home Assistant translations so the setup form explains exactly what the Hermes URL and token fields mean.

---

Hermes tools provided by the HA plugin

Voice tools provided by the voice plugin

---

Confirm the plugin is loaded

hermes plugins | grep voice_stack

Step 6 — Add the integration in Home Assistant

1. Open Settings → Devices & services.
2. Click Add integration.
3. Search for Hermes Voice Assistant.
4. Complete the setup form:

Visual check:

Home Assistant  →  http://<hermes-host>:7860  →  /api/hermes/ws

Do not enter http://homeassistant.local:8123 in the Hermes URL field. That URL is only used by Hermes itself when Hermes talks back to Home Assistant via HASS_URL.

1. Submit.

The integration adds:

• hermes.hermes_command service for HA-native service dispatch.
• hermes.voice_settings service for voice/dashboard helpers.
• Hermes status entities:
• sensor.hermes_gateway_status — Hermes gateway reachable or offline
• sensor.hermes_uptime_hours — how long Hermes has been running
• sensor.hermes_total_interactions — number of voice interactions
• sensor.hermes_total_errors — number of voice errors
• sensor.ha_ws_connection — HA WebSocket connection state
• sensor.hermes_voice_ready — voice pipeline ready flag
• sensor.hermes_tts_voice — configured default TTS voice
• sensor.hermes_stt_engine — configured STT engine
• sensor.hermes_wake_word — configured wake-word keyword(s)
• sensor.hermes_media_player — configured media player for TTS

---

Page 2 — Voice pipeline

Mockup of the Step 2 — Voice pipeline options page. The Step 1 — Allow-listed entities & SSL page appears first, with an entity-ID editor and an SSL toggle.

Values are persisted in the config entry options. After saving, Hermes reads them from entry.options on every restart. Screenshots of the live UI are welcome via PR.

---

Troubleshooting