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>