# 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.