# 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 - - - - - -