Add Athena WebRTC bridge for OpenClaw Talk

services/athena-realtime-voice/README.md

@@ -0,0 +1,74 @@
+# 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. 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.