77 lines
4.0 KiB
Markdown
77 lines
4.0 KiB
Markdown
# Athena realtime voice bridge (experimental)
|
|
|
|
This independent service lets OpenClaw's existing browser Talk UI use Athena
|
|
Whisper, OpenClaw's agent, and Athena Qwen3-TTS through the browser's supported
|
|
OpenAI-style WebRTC transport. It does not modify OpenClaw or switch an Athena
|
|
profile. The existing `gateway-relay` path remains available.
|
|
|
|
Flow: OpenClaw's `athena-talk` plugin signs a single-use 60-second browser token;
|
|
the browser posts an SDP offer to this service; microphone audio is sent over
|
|
WebRTC; Athena transcribes it; the service asks OpenClaw to run
|
|
`openclaw_agent_consult`; Athena speaks the returned text over the same WebRTC
|
|
connection. This is a half-duplex prototype. Barge-in and remote-network TURN
|
|
support are not implemented.
|
|
|
|
Required service environment:
|
|
|
|
| Name | Purpose |
|
|
| --- | --- |
|
|
| `OPENCLAW_PUBLIC_KEY_URL` | Existing OpenClaw HTTPS origin plus `/plugins/athena-talk/realtime/public-key`. The service fetches the plugin's public verification key. |
|
|
| `ATHENA_API_BASE_URL` | Router API base, `http://router:8081/v1` in the Compose deployment. |
|
|
| `ATHENA_API_KEY` | Router key, if required. |
|
|
| `OPENCLAW_ORIGIN` | Exact HTTPS origin of the UI, e.g. `https://oc.casaderoll.de`. |
|
|
| `PORT` | HTTP listen port; default 8090. The Compose service shares the existing WireGuard gateway network namespace. |
|
|
|
|
The plugin provides an HTTPS offer route on the existing OpenClaw origin and
|
|
forwards SDP to this service. Configure
|
|
`talk.realtime.providers.athena-talk.realtimeUpstreamUrl` with Athena's internal
|
|
HTTP URL ending in `/v1/realtime/calls`. Set the service's
|
|
`OPENCLAW_PUBLIC_KEY_URL` to the OpenClaw HTTPS public-key route above. No new
|
|
secret is needed in OpenClaw: its plugin keeps a private signing key in memory,
|
|
and the service receives only the public key. Select
|
|
`talk.realtime.transport: "webrtc"` only after the service is reachable. Keep
|
|
`gateway-relay` as a rollback option.
|
|
|
|
The WebRTC media connection needs a route from the client device to Athena's
|
|
ICE candidate addresses. The service runs directly inside Athena's existing
|
|
private WireGuard network namespace, so home/VPN clients can reach it at
|
|
`192.168.1.212:8090`; the OpenClaw HTTPS proxy covers signaling only. Clients
|
|
outside the private network need TURN support, which is not implemented.
|
|
|
|
The deployed service is `mike-ai-realtime-voice` in `compose.yaml`. It uses no
|
|
GPU and does not switch Athena's active model profile. Deploy it with the
|
|
stack's normal environment:
|
|
|
|
```sh
|
|
cd /opt/mike-ai/stack
|
|
docker compose --env-file /etc/mike-ai/stack.env up -d --no-deps --build realtime-voice
|
|
```
|
|
|
|
OpenClaw 2026.9.4 uses the `athena-talk` plugin version 1.1.0 with
|
|
`talk.realtime.transport` set to `webrtc` and
|
|
`talk.realtime.providers.athena-talk.realtimeUpstreamUrl` set to
|
|
`http://192.168.1.212:8090/v1/realtime/calls`. On the Mac, turn off
|
|
“Echtzeitweiterleitung über Gateway verwenden”, which applies only to the
|
|
older `gateway-relay` mode. The tested Mac UI showed this switch on again
|
|
after navigation despite a false native preference; this UI behavior remains
|
|
unresolved. A Gateway restart after plugin installation was
|
|
needed to register the two new HTTPS routes. The plugin signs short-lived
|
|
session tokens with an in-memory Ed25519 key; the service fetches only its
|
|
public key. A Gateway restart rotates the key automatically.
|
|
|
|
Local isolated test (fake STT/TTS, synthetic microphone and speaker audio):
|
|
|
|
```sh
|
|
python3.11 -m venv .venv
|
|
.venv/bin/pip install -r requirements.txt
|
|
.venv/bin/python -m unittest -v test_smoke.py
|
|
```
|
|
|
|
The synthetic microphone test passed over the actual OpenClaw HTTPS offer
|
|
route and WireGuard media path with production Whisper and Qwen3-TTS on
|
|
2026-09-16. It supplied a fake agent result; it does not prove that the Mac
|
|
or browser UI completes a real agent-consult turn. Keep this integration
|
|
experimental until that UI round trip has been observed.
|
|
For isolated tests, `ATHENA_TALK_REALTIME_SECRET` can replace
|
|
`OPENCLAW_PUBLIC_KEY_URL`; do not use that test mode in the deployed setup.
|