Gateway-geeignetes Pairing (Option B)

Geräte und Nutzer koppeln. Wer mit dem Agenten sprechen darf—der Gateway ist die Quelle der Wahrheit. Beim Gateway-geeigneten Pairing ist der Gateway die Quelle der Wahrheit dafür, welche Nodes sich verbinden dürfen. UIs (macOS-App, zukünftige Clients) sind nur Frontends, die ausstehende Anfragen genehmigen oder ablehnen.

Wichtig: WS-Nodes nutzen Geräte-Pairing (Rolle node) während connect. node.pair.* ist ein separater Pairing-Store und begrenzt nicht den WS-Handshake. Nur Clients, die explizit node.pair.* aufrufen, nutzen diesen Ablauf.

Konzepte

Ausstehende Anfrage: ein Node hat um Beitritt gebeten; erfordert Genehmigung.
Gekoppelter Node: genehmigter Node mit ausgestelltem Auth-Token.
Transport: der Gateway-WS-Endpunkt leitet Anfragen weiter, entscheidet aber nicht über die Mitgliedschaft. (Legacy-TCP-Bridge-Unterstützung ist veraltet/entfernt.)

Ablauf des Pairings

Ein Node verbindet sich mit dem Gateway-WS und fordert Pairing an.
Der Gateway speichert eine ausstehende Anfrage und sendet node.pair.requested.
Sie genehmigen oder lehnen die Anfrage ab (CLI oder UI).
Bei Genehmigung stellt der Gateway einen neuen Token aus (Tokens werden beim erneuten Koppeln rotiert).
Der Node verbindet sich mit dem Token neu und ist nun „gekoppelt“.

Ausstehende Anfragen laufen automatisch nach 5 Minuten ab.

CLI-Ablauf (headless-freundlich)


openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status zeigt gekoppelte/verbundene Nodes und ihre Fähigkeiten.

API-Oberfläche (Gateway-Protokoll)

Ereignisse:

node.pair.requested — wird gesendet, wenn eine neue ausstehende Anfrage erstellt wird.
node.pair.resolved — wird gesendet, wenn eine Anfrage genehmigt/abgelehnt/abgelaufen ist.

Methoden:

node.pair.request — ausstehende Anfrage erstellen oder wiederverwenden.
node.pair.list — ausstehende + gekoppelte Nodes auflisten.
node.pair.approve — ausstehende Anfrage genehmigen (stellt Token aus).
node.pair.reject — ausstehende Anfrage ablehnen.
node.pair.verify — { nodeId, token } verifizieren.

Hinweise:

node.pair.request ist pro Node idempotent: wiederholte Aufrufe liefern dieselbe ausstehende Anfrage.
Genehmigung erzeugt immer einen neuen Token; ein Token wird nie von node.pair.request zurückgegeben.
Anfragen können silent: true als Hinweis für Auto-Genehmigungs-Abläufe enthalten.

Auto-Genehmigung (macOS-App)

Die macOS-App kann optional eine stille Genehmigung versuchen, wenn:

die Anfrage als silent markiert ist und
die App eine SSH-Verbindung zum Gateway-Host mit demselben Nutzer verifizieren kann.

Schlägt die stille Genehmigung fehl, fällt sie auf die normale „Genehmigen/Ablehnen“-Abfrage zurück.

Speicherung (lokal, privat)

Der Pairing-State wird unter dem Gateway-State-Verzeichnis gespeichert (Standard ~/.clawdbot):

~/.clawdbot/nodes/paired.json
~/.clawdbot/nodes/pending.json

Wenn Sie CLAWDBOT_STATE_DIR überschreiben, wandert der Ordner nodes/ mit.

Sicherheitshinweise:

Tokens sind geheim; paired.json vertraulich behandeln.
Token-Rotation erfordert erneute Genehmigung (oder Löschen des Node-Eintrags).

Transport-Verhalten

Der Transport ist zustandslos; er speichert keine Mitgliedschaft.
Ist der Gateway offline oder Pairing deaktiviert, können Nodes nicht koppeln.
Bei Remote-Modus des Gateways erfolgt Pairing weiterhin gegen den Store des Remote-Gateways.