Clawnet Refactor: Protokoll- und Auth-Vereinheitlichung

Du kennst das Problem: Du baust ein System und plötzlich hantierst du mit zwei völlig verschiedenen Protokoll-Stacks. Einer kümmert sich um den Control Plane, der andere um den Datentransport der Nodes. Das macht die Wartung kompliziert und führt oft zu Inkonsistenzen bei der Security. Wenn dann noch Sicherheitsabfragen auf einem Remote-Server aufpoppen, statt direkt in deinem Interface, wird der Workflow unnötig unterbrochen.

Wir räumen mit Clawnet auf. Das Ziel ist ein einziges Protokoll, eine klare Identität pro Gerät und eine Security, die überall funktioniert – egal ob auf dem Desktop oder mobil.

Voraussetzungen

• Gateway mit WebSocket Support
• Clients (macOS App, CLI, iOS, Android oder Headless Node)
• Device Keypairs für die Identität
• TLS Zertifikate (für TLS Pinning)

Schnellstart

In weniger als 5 Minuten verbindest du einen Client über das neue Protokoll:

1. Verbindung aufbauen: Der Client verbindet sich unauthentifiziert mit dem Gateway.
2. Pairing Request: Das Gateway erstellt automatisch eine Anfrage für die deviceId.
3. Freigabe: Ein Operator sieht den Prompt in seiner UI und bestätigt die Verbindung.
4. Credential Issue: Das Gateway stellt Token aus, die fest an den Public Key deines Geräts gebunden sind.
5. Reconnect: Der Client verbindet sich authentifiziert neu.

Ein Protokoll, zwei Rollen

Wir verabschieden uns von der Trennung zwischen Gateway WebSocket und Bridge. Zukünftig gibt es nur noch ein WebSocket Protokoll, bei dem die Rolle über die Berechtigungen entscheidet.

Node (Capability Host)

• Registriert caps, commands und Permissions.
• Empfängt invoke Commands wie system.run oder camera.*.
• Sendet Events wie voice.transcript.
• Hat keinen Zugriff auf Config- oder Session-APIs.

Operator (Control Plane)

• Voller Zugriff auf die API (gesteuert über Scopes).
• Empfängt alle Approvals zentral.
• Führt keine OS-Aktionen direkt aus, sondern routet diese an Nodes.

Scopes für Operatoren

Um den Zugriff granular zu steuern, nutzen wir vier Scopes:

• operator.read: Status und Ansicht.
• operator.write: Agent-Runs und Nachrichten.
• operator.admin: Config, Channels und Modelle.
• operator.approvals: Bestätigung von Sicherheitsabfragen.

TLS und Identität

Sicherheit ist kein optionales Feature. Wir weiten das TLS Pinning der Bridge auf das gesamte WebSocket Protokoll aus.

• Stable IDs: Jedes Gerät nutzt einen Fingerprint seines Public Keys als deviceId.
• Cute Slugs: Für die UI nutzen wir menschenlesbare Labels wie scarlet-claw oder mantis-pinch.
• Device-bound Auth: Wir nutzen Keypairs statt einfacher Bearer Token. Das verhindert Replay-Attacks, da das Gateway Nonces sendet, die der Client signieren muss.

Zentralisierte Approvals

Bisher tauchten Bestätigungsfenster oft dort auf, wo der Node lief – etwa auf einem entfernten Mac. Das ändern wir. Approvals sind jetzt Gateway-hosted.

1. Ein Agent sendet einen system.run Intent.
2. Das Gateway erstellt einen approval.requested Record.
3. Alle Operator-Clients erhalten den Prompt.
4. Die erste Entscheidung gewinnt (approval.resolve), das Gateway führt den Befehl auf dem Node aus.

Fehlerbehebung

Problem: Doppelte Einträge in der UI Wenn deine macOS App sowohl als UI als auch als Node auftaucht, liegt das an unterschiedlichen IDs. Lösung: Stelle sicher, dass beide Verbindungen dieselbe deviceId nutzen. Das Gateway führt diese dann automatisch zu einer “Instance” zusammen.

Problem: Remote Approvals kommen nicht an Der Prompt erscheint nicht auf deinem mobilen Gerät. Lösung: Prüfe, ob dein Client den Scope operator.approvals besitzt. Ohne diesen Scope werden keine aktiven Modals für System-Anfragen angezeigt.

Problem: Pairing schlägt fehl Die Verbindung wird abgelehnt, obwohl der Key korrekt ist. Lösung: Das Gateway nutzt bei lokalen Verbindungen (Loopback) eine Silent Approval Heuristik. Prüfe bei Remote-Verbindungen die Logs auf abgelaufene Nonces.

Nächste Schritte

• Protocol Specification
• Auth Flow Details
• Node Capabilities
• Migration Guide

AI Setup Assistant