"ideally brain tab should show from duckdb & duckdb should be updated for every conversation with OpenClaw from any of the channels"
— user, 2026-05-14

Status: PAUSED on upstream — NOT a [RELEASE] PR

Per the failure-mode escape clause in the task brief: the OSS gateway's token-auth handshake currently grants scopes=[], so the WS tap can connect but cannot call sessions.messages.subscribe (the only method that delivers inbound message bodies). Filed openclaw/openclaw#81775, referencing the canonical fix RFE openclaw/openclaw#80836 (gateway.auth.tokenScopes).

The code is correct, fully tested, and ready to ship the moment OpenClaw lands #80836 (or an equivalent way to grant operator.read to the loopback CLI token non-interactively). I dropped the [RELEASE] prefix so the auto-publish workflow does not ship a tap that can't actually capture anything to PyPI users today.

Architecture summary

clawmetry/gateway_tap.py is a single background thread the sync daemon spawns at startup. It:

1. Detects gateway URL + token from OPENCLAW_GATEWAY_TOKEN env or ~/.openclaw/openclaw.json (mirrors dashboard._detect_gateway_token so the daemon doesn't have to import Flask).
2. Opens a persistent WebSocket to ws://127.0.0.1:18789/, runs the OpenClaw protocol-3 connect handshake, then attempts sessions.messages.subscribe.
3. For every pushed event frame, _normalize_frame() projects it into the same (events_row, channel_messages_row) shape the existing JSONL parser produces (clawmetry/sync.py:_parse_channel_event) — so brain-history reads from DuckDB don't have to know which transport delivered the row.
4. Writes through local_store.ingest_many() (events) + ingest_channel_message() (channel_messages). The body-bearing WS-tap row beats the gateway-log parser's NULL-body ACK row via the existing COALESCE(excluded.body, channel_messages.body) upsert — so when both transports observe the same (provider, chat_id, message_id), the body sticks.
5. Wraps the whole loop in exponential backoff (2s → 60s) so any disconnect / gateway restart / scope rejection retries cleanly without crashing the daemon.

Wired into clawmetry/sync.py:run_daemon() right after the local_query server starts. Default-ON (per MOAT mandate feedback_local_store_default_off_killed_moat); opt out with CLAWMETRY_DISABLE_WS_TAP=1. Channel coverage matches _CHANNEL_DIRS (21 adapters) — the gateway-side subscribe is global rather than per-channel, but the list is documentation for any future per-channel API.

Limitations

• Inbound messages received while the daemon was offline are lost forever — OpenClaw has no replay buffer for in-memory channel state (openclaw/openclaw#42157). Real fix is OpenClaw upstream persistence.
• Live capture currently blocked on scope-grant gap. With OpenClaw 2026.5.7's default token-auth, connect succeeds but returns auth.scopes = []. Every method that delivers message bodies (sessions.messages.subscribe, sessions.subscribe, logs.tail, channels.status) then 401s with missing scope: operator.read. Filed openclaw/openclaw#81775, referencing canonical fix openclaw/openclaw#80836. Tap logs a single WARNING with the exact symptom and downgrades to a degraded-but-stable state (catches health snapshots only).
• health events from the gateway also stream over the same socket — we drop them in _normalize_frame() since the dedicated gateway.metric ingest path already covers them. No double-write.
• websocket-client is a soft dependency: if not installed, the tap logs a one-shot warning and the daemon's gateway-log parser path keeps running unchanged.

Verification

Mocked WS server (the only path that works today, pre-upstream-fix)

$ pytest tests/test_gateway_tap.py -v
============================== 11 passed in 1.69s ==============================

  test_normalize_telegram_inbound                          PASSED
  test_normalize_outbound_inferred_from_event_name          PASSED
  test_normalize_health_frame_returns_none                  PASSED
  test_normalize_epoch_seconds_coerced_to_iso               PASSED
  test_handle_frame_writes_event_and_channel_message        PASSED
  test_handle_frame_drops_unparseable_frame                 PASSED
  test_ws_tap_body_overwrites_parser_null_body              PASSED
  test_full_loop_against_stubbed_websocket                  PASSED
  test_disable_env_var_short_circuits_start                 PASSED
  test_detect_gateway_endpoint_reads_openclaw_json          PASSED
  test_detect_gateway_endpoint_returns_none_when_no_config  PASSED

test_full_loop_against_stubbed_websocket is the headline E2E: it injects a fake websocket module into sys.modules, drives GatewayTap.start() against a scripted responder that mints a connect-ok then a sub-ok then a real Telegram inbound payload, then asserts a row appears in channel_messages with the body intact.

Real Telegram message → DuckDB (post-upstream-fix)

Once openclaw/openclaw#80836 lands and ~/.openclaw/openclaw.json carries gateway.auth.tokenScopes: ["operator.read"]:

1. Restart clawmetry sync and check ~/.clawmetry/sync.log for:

   INFO gateway WS tap connected — capturing live channel events
   

   (vs the current connected (degraded — no message subscribe; granted scopes=[])).
2. Send a Telegram message to the OpenClaw bot.
3. Within ~1 sec, the body should appear at the head of /api/brain-history and via direct query:

   SELECT ts, provider, channel_id, direction, body
   FROM channel_messages
   WHERE provider = 'telegram'
   ORDER BY ts DESC LIMIT 5;

4. Stop the daemon, send another message (it'll be lost — see Limitations), restart, send a third — the third one should land. The second never will until OpenClaw adds replay (#42157).

Files touched

• clawmetry/gateway_tap.py (new, ~430 LOC) — the WS tap module
• clawmetry/sync.py (+13 LOC) — startup wiring inside run_daemon
• tests/test_gateway_tap.py (new, ~340 LOC) — 11 unit + integration tests

Connection status (in this worktree)

• Code: ready, all 11 tests pass.
• Real OpenClaw gateway in this dev environment: tap connects (handshake ok) but auth.scopes = [] rejects every message subscribe — verified by /tmp/probe_gateway_ws.py. Mock-only verification.

🤖 Generated with Claude Code