nexus/docs/audits/2026-07-30/openclaw-agent-first-hardening/ACCEPTANCE_EVIDENCE.md

# OpenClaw Agent-first Hardening — Acceptance Evidence

**Datum:** 2026-07-30
**Scope:** Security-Grenze, Gateway-Verbindung, Mutationssicherheit,
Eventprojektion, durable Runs, globaler Agent-first-Einstieg und wahrheitsgetreue
Telemetrie
**Ergebnis:** Lokale Implementierungs- und Testabnahme bestanden;
Live-Gateway-/Produktionsabnahme offen

## Abnahmeurteil

Die sieben priorisierten Hardening-Punkte sind im aktuellen Working Tree
implementiert und durch den unten dokumentierten automatisierten Baseline-Lauf
abgesichert. Das ist kein Produktionsfreigabe-Nachweis: Es wurde in diesem
Checkpoint weder ein reales Remote-Gerät gepaart noch ein vollständiger
OpenClaw-/OpenAI-Lauf in der Zielumgebung ausgeführt.

## 1. Security boundary

**Status:** lokal abgenommen

- `backend/Extensions/ServiceCollectionExtensions.cs` setzt eine
  authentifizierte Fallback-Policy.
- Nur Authentifizierungs-/Session-Bootstrap und explizite Health-Probes sind
  anonym. Die OpenClaw-, Run-, Event-, Dashboard-, Task-, Agent- und
  Security-Flächen bleiben geschützt.
- `backend/Services/RequestAuthorizationHelper.cs` behandelt `X-Agent-Id` nur
  nach bereits verifizierter Service- oder privilegierter User-Identität als
  allow-gelisteten Actor-Hinweis.
- OpenClaw-Control- und Run-Mutationen sind owner-only. Das MCP- und
  Bridge-Datenplane akzeptiert verifiziertes JWT oder `X-Nexus-Api-Key`, aber
  keinen frei gesetzten Agent-Header als Credential.
- Negative Auth-, Rollen- und Header-Eskalationsfälle liegen in
  `backend-tests/SecurityBoundaryTests.cs` sowie den fokussierten
  Controller-/MCP-Tests.

## 2. Reale Gateway-Verbindungsgrundlage

**Status:** Protokoll und Pairing-Zustand implementiert; Live-Pairing offen

- `backend/Services/OpenClawGatewayProtocol.cs` und
  `backend/Services/GatewayConnector.cs` verwenden Protocol v4 und den
  bestätigten Stable-Release-Pin `2026.7.1`. `2026.7.2-beta.1` ist als
  Vorabversion bewusst nicht der Default.
- Nur `127.0.0.1`, `::1` und `localhost` gelten als direkte Loopback-Topologie.
- `backend/Services/OpenClawDeviceIdentityStore.cs` persistiert die
  Ed25519-Geräteidentität und nach erfolgreichem Pairing den Device-Token.
- Die Challenge-Signatur bindet die kanonische v3-Payload an den vom Gateway
  gelieferten Nonce. `PAIRING_REQUIRED` samt konkreter Request-ID wird bis UI
  und Settings weitergegeben.
- Die Compose-Konfiguration hält Device- und Audit-Dateien in
  `nexus-openclaw-device` über Container-Neustarts stabil.
- Protokoll-, Versions-, Loopback-, Challenge-, Pairing- und
  Persistenzverhalten wird durch `backend-tests/GatewayConnectorTests.cs`,
  `backend-tests/OpenClawGatewayProtocolTests.cs` und
  `backend-tests/OpenClawDeviceIdentityAndAuditTests.cs` geprüft.

## 3. Zuverlässige Mutationen

**Status:** lokal abgenommen; Single-Writer-Grenze bleibt

- Frontend-Mutationen erzeugen über
  `frontend/src/services/mutationContext.ts` einen Idempotency Key, eine
  Correlation ID und einen gültigen W3C-`traceparent`.
- Der Backend-Rand leitet den Actor ausschließlich aus dem authentifizierten
  Principal ab. Die Invocation-Metadaten werden bis zum Gateway transportiert.
- `backend/Services/OpenClawOperationAuditStore.cs` speichert einen
  append-only Metadaten-Ledger mit gehashten Idempotency Keys, nicht Prompts,
  Tool-Argumenten, Rohresultaten oder Credentials.
- Ein gleicher Schlüssel und Intent liefert das vorhandene Ergebnis; ein
  abweichender Intent wird abgelehnt. Ein nach Neustart nicht sicher
  abgeschlossenes Ergebnis wird `in_doubt` und nicht automatisch wiederholt.
- Geschlossene OpenClaw-Control-Schemas erhalten kein erfundenes
  `params.idempotencyKey`. Nexus dedupliziert sie lokal. Durable Run-Aktionen
  persistieren ihre Idempotency- und Transition-Daten zusätzlich in
  PostgreSQL.

## 4. Eventprojektion

**Status:** lokal abgenommen

- `GET /api/v1/openclaw/events` liefert authentifiziertes SSE.
- `Last-Event-ID` und `lastEventId` unterstützen Replay aus dem begrenzten
  Connector-Buffer.
- Connection-, Heartbeat- und Gap-Events machen Verbindungs- und
  Replay-Zustand explizit. Run-, Session-, Tool-, Approval-, Artifact- und
  sonstige Gateway-Ereignisse werden klassifiziert, sequenziert und redigiert.
- Sequenzlücken und Resets bleiben sichtbar; ein veralteter Cursor löst einen
  autoritativen Refresh statt einer stillen Datenlücke aus.
- `frontend/src/services/openclawLive.ts` und
  `frontend/src/stores/openclaw.ts` verwenden SSE zuerst, reconnecten mit
  begrenztem Backoff und fallen nur bei fehlender Live-Verbindung auf
  60-Sekunden-Polling zurück.
- Backend-Abdeckung:
  `backend-tests/OpenClawEventProjectionTests.cs` und
  `backend-tests/OpenClawEventSubscriptionCoordinatorTests.cs`.
  Frontend-Abdeckung: `frontend/tests/openclaw-live.test.ts`.

## 5. Durable Run

**Status:** Start, Stop, Retry, Historie und Reconnect-Projektion lokal
abgenommen; Same-run-Resume bewusst nicht verfügbar

- Die Migration
  `backend/Data/Migrations/20260730130442_AddOpenClawRunProjection.cs`
  ergänzt dauerhafte Runs und Transition-Historie.
- `backend/Controllers/OpenClawRunsController.cs`,
  `backend/Services/OpenClawRunService.cs`,
  `backend/Services/OpenClawRunGateway.cs` und
  `backend/Repositories/OpenClawRunRepository.cs` implementieren:
  - Liste und Detail;
  - persist-before-dispatch Start;
  - exakten Run-Stop ohne Session-weites Abbrechen;
  - Retry als korrelierten neuen Run;
  - Nexus-Transitionen plus redigierte Gateway-Historie;
  - Task-, Projekt-, Session-, Actor-, Correlation- und Trace-Bezug;
  - Event-Reconciliation einschließlich per-Run-Sequenzlücke.
- `/runs/:id` zeigt Zustand, Korrelationen, Transitionen, Recovery-Aktionen
  und Sync-/Gap-Zustand. Resume ist deaktiviert und der Backend-Endpunkt
  antwortet `unsupported`, da der gepinnte Gateway-Vertrag keinen belegten
  Same-run-Resume-RPC bietet.
- Abdeckung:
  `backend-tests/OpenClawRunServiceTests.cs`,
  `backend-tests/OpenClawRunGatewayTests.cs` und
  `frontend/tests/openclaw-runs.test.ts`.

## 6. Globaler Agent-first-Einstieg

**Status:** lokal abgenommen

- `Ctrl/Cmd+K` öffnet
  `frontend/src/components/mission-control/CommandPalette.vue` auf allen
  authentifizierten Routen.
- Die Palette navigiert zu Kernflächen und geladenen Projekten, Tasks, Agents
  und Sessions. Für Task, Projekt und Agent kann sie einen korrelierten Run
  vorausfüllen.
- Iris ist ein globales, standardmäßig geschlossenes Modal. Der gesendete
  Kontext ist auf Route, Surface, Entity-Typ und Entity-ID begrenzt.
- `backend/Services/MissionControlContextFormatter.cs` normalisiert diesen
  Kontext und markiert ihn als nicht vertrauenswürdige Metadaten, bevor die
  eigentliche Nutzeranweisung folgt.
- Keyboard-Auswahl, Escape, gegenseitiger Ausschluss der Dialoge und
  Fokus-Rückgabe sind in der UI implementiert.
- Abdeckung:
  `frontend/tests/mission-control.test.ts` und
  `backend-tests/MissionControlContextFormatterTests.cs`.

## 7. Wahrheitsgetreue Telemetrie

**Status:** lokal abgenommen

- `backend/Services/DashboardService.cs` übernimmt Fortschritt nur aus einem
  gemeldeten Nexus-Task und Tokens nur aus einer gemeldeten
  OpenClaw-Session.
- Cost bleibt `null`, solange die Runtime keinen autoritativen Wert liefert.
- Dashboard- und Agentenkomponenten zeigen unbekannte Werte als
  „Nicht gemeldet“ und erzeugen keine synthetischen Thinking-Items,
  hartcodierten Fortschritte, Kosten, Laufzeiten oder nächsten Schritte.
- Reale Runtime-Status- oder Activity-Typen dürfen weiterhin „thinking“
  enthalten; entfernt wurde die präsentativ erfundene Telemetrie, nicht ein
  autoritatives Ereignis.

## Automatisierte Baseline

Ausgeführt am 2026-07-30 im Repository-Root beziehungsweise in `frontend/`:

| Gate | Ergebnis |
|---|---|
| `.tools\dotnet\dotnet.exe test backend-tests/Nexus.Api.Tests.csproj --configuration Release --no-restore` | bestanden: 271, fehlgeschlagen: 0, übersprungen: 0 |
| `pnpm typecheck` | bestanden |
| `pnpm test` | 6 Dateien, 11 Tests bestanden |
| `pnpm build` | bestanden; 1.897 Module transformiert |

## Operierte Browser-QA

Ausgeführt am 2026-07-30 gegen die sichtbar als `QA SIMULATION` markierte
Repository-Fixture `scripts/qa/openclaw-ui-mock.mjs`:

- alle 19 Seitenrouten bei 1440 px ohne Dokument-Overflow oder sichtbare
  Alerts; die bereits authentifizierte `/login`-Navigation leitete erwartbar
  zu `/dashboard`;
- alle 18 authentifizierten Seiten bei 375 px ohne Dokument-Overflow;
- Dashboard, Run Control, Run Detail, Task Board, Calendar und Settings
  zusätzlich bei 768, 1024 und 1920 px ohne Dokument-Overflow;
- Command Palette per Button und `Ctrl/Cmd+K`, Escape-Schließen,
  Fokus-Rückgabe und Objekt-Navigation;
- Iris als standardmäßig geschlossenes Modal mit erhaltenem Run-/Task-Kontext;
- Task-korrelierter Run-Start, exakter Stop und Retry als neuer korrelierter
  Run mit unveränderter Quellhistorie;
- keine Browser-Warnungen oder -Fehler im finalen Konsolencheck.

Die Fixture führte keine reale OpenClaw- oder OpenAI-Aktion aus. Diese
Browser-QA belegt ausschließlich UI-Verträge, Interaktion, responsive
Geometrie und den simulierten Lifecycle.

## Verbleibende Grenzen vor Produktionsfreigabe

1. **Live-Gateway:** Remote-Pairing mit realer Request-ID, Device-Token-Reuse,
   Reconnect und Versionsfehlermodus in der Zielumgebung beweisen.
2. **End-to-end Provider:** Einen vollständigen
   `Nexus -> OpenClaw -> OpenAI -> Nexus`-Lauf ausführen und belegen, dass
   OpenAI in OpenClaw tatsächlich der primäre Provider ist.
3. **Live-Events:** SSE-Reconnect, Cursor-Replay, Gap-Recovery und
   Run-Reconciliation unter echtem Gateway-Verkehr und längerer Laufzeit
   testen.
4. **Multi-Replica:** Den lokalen JSONL-Idempotency-Ledger vor horizontaler
   Skalierung durch einen geteilten transaktionalen Ledger mit eindeutigem
   Key-Claim ersetzen.
5. **Resume und weitere Control-Flächen:** Same-run-Resume bleibt unsupported.
   Tool-/Policy-, Channel-, Node-, Connector-, Secret- und vollständige
   Schedule-Verwaltung sind weiterhin Produkt-Roadmap, nicht Teil dieses
   Hardening-Slices.
6. **Datenbank-/Deployment-Nachweis:** Die neue EF-Migration muss in einer
   PostgreSQL-Zielumgebung angewendet und zurücklesbar geprüft werden. In diesem
   Checkpoint gab es keinen Commit, Push oder Deployment.

## Kanonische Folgedokumente

- [Agent-First Mission Control](../../../AGENT_FIRST_MISSION_CONTROL.md)
- [OpenClaw Gateway connection contract](../../../OPENCLAW_GATEWAY_CONNECTION.md)
- [Mission Control Roadmap](../../../MISSION_CONTROL_ROADMAP.md)
- [Route and agent-first evaluation](ROUTE_AND_AGENT_FIRST_EVALUATION.md)