nexus/docs/OPENCLAW_GATEWAY_CONNECTION.md

OpenClaw Gateway connection contract

Status: Attach-&-Adopt-Vertrag implementiert; produktive externe Client-Identität und Live-Abnahme offen Stand: 2026-07-30

Nexus ist die einzige browserseitige Control Plane. OpenClaw bleibt die Runtime- und Datenautorität. Gateway-Credentials, Ed25519-Private-Key, Device-Token, Provider-Secrets und OpenAI-Schlüssel bleiben serverseitig und werden weder an den Browser noch in OpenClaw-Projektionen oder PostgreSQL gegeben.

Produktions- und Kompatibilitätsgrenze

• Der Connector verwendet Gateway Protocol v4 und ist standardmäßig auf den geprüften OpenClaw-Stand 2026.7.1 gepinnt.
• Nexus verwendet die externe Client-ID nexus und imitiert weder gateway-client/backend noch Control UI oder CLI. Diese Identitäten sind OpenClaw-intern reserviert.
• Die stabile OpenClaw-Client-ID-Registry des gepinnten Stands unterstützt noch keine externe Nexus-/Generic-Operator-ID. Deshalb bleibt der produktive Connector standardmäßig mit OpenClawSetup:ExternalClientIdentitySupported=false beziehungsweise OPENCLAW_EXTERNAL_CLIENT_ID_SUPPORTED=false experimentell blockiert.
• Das Flag darf erst für eine OpenClaw-Version aktiviert werden, deren dokumentierter Client-Vertrag die verwendete externe Identität tatsächlich akzeptiert und gegen die Nexus-Contract-Tests gepinnt wurde.
• Lokale Mock-, Contract- und UI-Tests beweisen nicht, dass dieser Upstream- Blocker gelöst ist. Eine produktive Verbindung oder Managementfreigabe darf bis dahin nicht behauptet werden.

Autorisierungsgrenze

• ASP.NET Core verwendet eine authenticated-by-default Fallback Policy. Nur die Auth-Bootstrap-/Session-Endpunkte und explizite Liveness-/Gateway-Health- Probes sind anonym.
• Alle Setup-, Agent-Datei-, Workspace- und Config-Routen sind owner-only. Andere /api/v1/openclaw/*-Leserouten sind authentifiziert; Control- und Run-Mutationen bleiben owner-only.
• X-Agent-Id ist niemals Authentifizierung. Der Header ist nur nach bereits verifizierter Service- oder privilegierter Benutzeridentität ein allow-gelisteter Actor-Hinweis.
• OpenClaw-Schreibzugriffe benötigen gleichzeitig:
  • einen vom Gateway beworbenen RPC;
  • den erforderlichen Operator-Scope;
  • die lokal persistierte ManagementEnabled-Freigabe;
  • Rate Limit, Audit und einen Idempotency Key; sowie
  • den aktuellen Ressourcen- oder Config-Hash.

Persistiertes Profil und Secret Ownership

Nexus verwaltet in der ersten Ausbaustufe exakt ein Profil mit der festen ID primary. PostgreSQL speichert nur nicht geheime Verbindungs- und Adoptionsmetadaten:

• normalisierten Endpoint und Discovery-Quelle;
• erforderliche OpenClaw-Version und optionalen TLS-Fingerprint;
• Setup-/Adoption-State und lokale Managementfreigabe;
• Capability-Hash;
• Zeitstempel und Concurrency-Version.

Der Device-Key und ein ausgestellter Device-Token liegen ausschließlich im serverseitigen Device-State. Der Token ist an normalisierten Endpoint, TLS-Fingerprint, Rolle und Scopes gebunden. OpenAI-Schlüssel, Gateway-Passwörter und Provider-Secrets werden nicht in diesem Profil gespeichert.

Ein Bootstrap-Token kann beim Attach entweder maskiert im Owner-Formular oder über eine serverseitige Secret-Referenz übergeben werden. Der Klartext lebt nur im Arbeitsspeicher, bis OpenClaw einen gebundenen Device-Token ausstellt. Nexus gibt ihn nicht zurück und schreibt ihn weder in PostgreSQL noch in Auditdaten.

GatewayConnector:DeviceStatePath enthält Private Key, Public-Key-Metadaten und gebundene Device-Tokens. GatewayConnector:OperationAuditPath enthält den append-only Mutationsledger. Compose verwendet dafür:

• /var/lib/nexus/openclaw/device-state.json;
• /var/lib/nexus/openclaw/operation-audit.jsonl; und
• das benannte Volume nexus-openclaw-device.

Auf Unix setzt Nexus Verzeichnisse auf 0700 und Dateien auf 0600. Ein korruptes Identity- oder Audit-File scheitert geschlossen; Nexus rotiert nicht still eine neue Identität und wiederholt keinen unklaren Schreibvorgang.

Transport- und Discovery-Regeln

Discovery ist absichtlich begrenzt. Nexus prüft nur:

• einen bereits konfigurierten Endpoint;
• Baos bekannten Docker-DNS-Kandidaten openclaw-gateway:18789;
• Loopback;
• host.docker.internal; und
• mDNS nur nach einer ausdrücklichen Owner-Aktion. Der aktuelle Build meldet mDNS als unsupported und führt dann ebenfalls keinen Netzwerkscan aus.

Es gibt keinen Subnetzscan und keinen Zugriff auf den Docker-Socket.

Externe Ziele benötigen wss:// und einen bestätigten SHA-256- Zertifikatfingerprint. Klares ws:// ist nur für Loopback oder eine ausdrücklich erlaubte interne Docker-Verbindung zulässig. Ein Endpoint- oder TLS-Pin-Wechsel erzwingt eine neue Vertrauensprüfung; ein alter gebundener Device-Token darf nicht still weiterverwendet werden.

Owner-Flow: Erkennen, Verbinden und Übernehmen

Der Setup Center in /settings führt durch einen zustandsbehafteten, read-only-first Ablauf:

1. Erkennen: Bekannte Kandidaten finden oder einen expliziten Endpoint eingeben.
2. Prüfen: Transport, TLS-Pin, Version, Protokoll, externe Client- Kompatibilität und erreichbare Capabilities prüfen.
3. Verbinden: Mit einem einmaligen Bootstrap-Secret nur operator.read anfordern und bei Bedarf die exakte PAIRING_REQUIRED-Request-ID anzeigen.
4. Verifizieren: Nach externer Pairing-Freigabe Endpoint, Device, Rolle, Scopes und Capabilities erneut prüfen.
5. Read-only-Inventar: Agenten, Agent-Dateien, Modelle, Cron Jobs und weitere beworbene Ressourcen live lesen.
6. Übernehmen: Live-Inventar zurückgeben und nur Profilzustand, Capability-Hash und Adoptionszeitpunkte persistieren. Nexus kopiert keine Agent-Dateien, Cron Jobs, Channels, Nodes, Modelle oder Provider-Credentials.
7. Verwaltung freigeben: In einer separaten, sichtbaren Aktion operator.read plus die tatsächlich benötigten Adminrechte anfordern. Die Scope-Erweiterung benötigt eine neue OpenClaw-Pairing-Freigabe. Erst danach kann die lokale ManagementEnabled-Freigabe aktiv werden.

Eine bereits mit Admin-Scope verbundene, aber noch nicht adoptierte Instanz erfüllt den read-only-first Vertrag nicht und kann nicht still übernommen werden.

Setup-API

Alle Routen sind owner-only und für Mutationen rate-limited:

Methode	Pfad	Zweck
GET	/api/v1/openclaw/setup	Profil-, Pairing-, Trust-, Scope- und Adoptionsstatus
POST	/api/v1/openclaw/setup/discover	Ausschließlich bekannte Kandidaten ermitteln
POST	/api/v1/openclaw/setup/probe	Endpoint und Vertrauensvertrag ohne Adoption prüfen
POST	/api/v1/openclaw/setup/attach	Read-only-Verbindung mit flüchtigem Bootstrap-Secret beginnen
POST	/api/v1/openclaw/setup/verify	Pairing, Scopes, Version und Capabilities neu verifizieren
POST	/api/v1/openclaw/setup/adopt	Read-only-Live-Inventar und Fingerprints übernehmen
POST	/api/v1/openclaw/setup/management	Bewussten Management-Scope-Upgrade starten oder bestätigen
DELETE	/api/v1/openclaw/setup/connection	Bestätigt detachieren

Detach verlangt den bestätigten Endpoint und die Device-ID. Nexus entfernt das primary-Profil, schließt den aktiven Socket, deaktiviert das lokale Management-Gate und entfernt den an diese Verbindung gebundenen Device-Token. Der langfristige Nexus-Device-Key bleibt bestehen. Ein separat konfiguriertes Bootstrap-Secret muss der Operator weiterhin an dessen serverseitiger Quelle entfernen.

Offizieller OpenClaw-Wizard

Für ein erreichbares neues OpenClaw rendert Nexus den offiziellen Gateway- Wizard, statt Installations- oder Migrationslogik nachzubauen:

Methode	Pfad	OpenClaw-RPC
POST	/api/v1/openclaw/setup/wizard/start	wizard.start
POST	/api/v1/openclaw/setup/wizard/next	wizard.next
GET	/api/v1/openclaw/setup/wizard/{sessionId}	wizard.status
POST	/api/v1/openclaw/setup/wizard/{sessionId}/cancel	wizard.cancel

Der Wizard ist nur für eine verbundene, management-freigegebene Instanz mit beworbenen wizard.*-Methoden und operator.admin verfügbar. Nexus erzwingt den Setup-Flow mit installDaemon=false, redigiert sensible Schritte und akzeptiert keine Secret-Antwort aus einem unsicheren Browserfeld. Nexus installiert keine Pakete, startet keine SSH-Installation und führt weder migrate noch doctor --fix automatisch aus.

Runtime-, Config- und Cron-Autorität

Nach Adoption liest Nexus OpenClaw-Ressourcen weiterhin live:

• Agenten über agents.list;
• erlaubte Bootstrap-Dateien über agents.files.list/get/set;
• weitere Workspace-Dateien read-only über agents.workspace.list/get;
• Konfiguration über config.schema.lookup, config.get und config.patch;
• Cron Jobs und deren Run-Historie über die typisierten cron.*-RPCs; und
• Modell-Authentifizierungsstatus über eine redigierte models.authStatus-Projektion.

Datei- und Config-Schreibvorgänge re-readen vor der Mutation, lehnen Drift mit 409 ab und verifizieren das Ergebnis anschließend durch erneutes Lesen. Die UI behauptet keinen Hot Reload, wenn OpenClaw ihn nicht ausdrücklich bestätigt. Secrets werden nie aus einem Config-Snapshot oder Modell-Authstatus projiziert.

Mutation correlation und Idempotenz

Der Backend-Layer leitet oder akzeptiert:

• Idempotency-Key;
• X-Correlation-ID;
• W3C traceparent; und
• den authentifizierten Actor (sub).

Actor, Ziel, Operationszustand, Intent-Fingerprint und ein SHA-256-Hash des Idempotency Keys werden lokal ohne Prompts, Dateiinhalt, Tool-Argumente, ungefilterte Ergebnisse oder Credentials auditiert. Unterstützt das gepinnte OpenClaw-Schema kein idempotencyKey, dedupliziert Nexus lokal und sendet kein undokumentiertes Feld. Ein unklarer in_doubt-Zustand wird nicht automatisch wiederholt.

Der JSONL-Ledger ist ein Single-Writer-Vertrag für genau eine Nexus-API-Instanz. Mehrere Replikas benötigen vor Schreibfreigabe einen gemeinsamen transaktionalen Ledger.

Event- und Run-Projektionen

GET /api/v1/openclaw/events ist eine authentifizierte SSE-Projektion über den begrenzten Gateway-Eventpuffer. Sie unterstützt Last-Event-ID, Connection-, Heartbeat- und Gap-Signale und redigiert Payloads vor der Browsergrenze. Ein Cursor außerhalb des Puffers erzwingt einen autoritativen Refresh.

Nexus persistiert Durable Runs und ihre Transitionen in PostgreSQL, ohne OpenClaws Runtimezustand zu übernehmen. Start, exakter Stop und korrelierter Retry sind implementiert. Same-run Resume bleibt explizit unsupported, bis der gepinnte Gateway-Vertrag einen belegten RPC bereitstellt.

Abnahmegrenze

Lokale Contract-, Backend-, Frontend- und Browserprüfungen können Routing, Validierung, Redaction, Least Privilege, Hashkonflikte, Idempotenz und UI-Zustände belegen. Sie beweisen nicht:

• eine offiziell unterstützte externe Nexus-/Generic-Client-ID;
• eine reale Remote-Pairing- und Scope-Upgrade-Sequenz;
• Live-Schreibvorgänge gegen eindeutig benannte Testobjekte auf Baos OpenClaw; oder
• einen vollständigen Nexus -> OpenClaw -> OpenAI -> Nexus-Lauf.

Diese Nachweise sind verpflichtende Produktionsblocker. Live-Schreibtests, Pairing-Freigaben, OpenClaw-Patches, Deployment und Zugriffe außerhalb von Baos ausdrücklich freigegebenen Ressourcen gehören nicht zu diesem Implementierungscheckpoint.

Offizielle Protokollquellen

• https://github.com/openclaw/openclaw/blob/v2026.7.1/packages/gateway-protocol/src/client-info.ts
• https://github.com/openclaw/openclaw/blob/v2026.7.1/docs/gateway/protocol.md
• https://docs.openclaw.ai/gateway/operator-scopes
• https://docs.openclaw.ai/gateway/configuration
• https://docs.openclaw.ai/reference/wizard
• https://docs.openclaw.ai/cli/cron