nexus/docs/audits/2026-07-28/openclaw-core-integration/IMPLEMENTATION_EVIDENCE.md

OpenClaw Core Integration — Implementation Evidence

Stand: 2026-07-28 Scope: Nexus frontend, authenticated API facade, OpenClaw Gateway transport, core-route wiring and operated browser QA.

Ergebnis

Nexus now has one browser-safe OpenClaw control-plane path:

Browser
  -> authenticated Nexus API
  -> IOpenClawControlService
  -> IGatewayConnector
  -> OpenClaw Gateway protocol v4
  -> provider and tools selected by OpenClaw

The browser never receives an OpenClaw token, password or OpenAI credential. OpenClaw remains authoritative for runtime agents, sessions, tasks, approvals, cron jobs, models and runtime events. Nexus remains authoritative for users, projects, product tasks, notifications and the control-plane UX.

This checkpoint is a functional vertical slice, not yet proof that the deployed OpenClaw instance and OpenAI provider are production-ready. The repository has contract coverage and a clearly labelled browser-QA simulation; a real credentialed OpenClaw/OpenAI smoke test remains required.

Protocol-v4 connector

GatewayConnector and OpenClawGatewayProtocol now provide:

• connect.challenge detection followed by a protocol-v4 connect request and validated hello-ok;
• request/response correlation with backend-only request IDs;
• advertised method, event and granted-scope discovery;
• configurable handshake/RPC timeouts and receive-frame size limits;
• bounded recent-event buffering;
• reconnect backoff with jitter and explicit initializing/reconnecting/disconnected/failed/connected states;
• optional exact Gateway-version pinning through OPENCLAW_REQUIRED_VERSION;
• fail-closed method availability checks before RPC invocation;
• safe error projection without returning credentials or raw transport state to the browser.

The current trusted backend flow intentionally omits device identity only for the OpenClaw-supported direct-loopback/shared-secret topology. A remote or container-to-host Gateway topology needs a paired device identity and signed challenge response before it can be claimed production-ready.

Typed Nexus facade

All endpoints below require Nexus authentication. Mutations additionally require the owner role and use the existing agent rate-limit policy.

Method	Endpoint	OpenClaw operation
GET	/api/v1/openclaw/connection	Connection and recovery state
GET	/api/v1/openclaw/capabilities	Advertised method/scope matrix
GET	/api/v1/openclaw/overview	Aggregated control-plane read model
GET	/api/v1/openclaw/tasks	tasks.list
POST	/api/v1/openclaw/tasks/{id}/cancel	tasks.cancel
GET	/api/v1/openclaw/sessions	sessions.list
POST	/api/v1/openclaw/sessions/abort	sessions.abort
POST	/api/v1/openclaw/sessions/model	sessions.patch
GET	/api/v1/openclaw/cron	cron.list
POST	/api/v1/openclaw/cron/{id}/run	cron.run with force mode
GET	/api/v1/openclaw/approvals	approval snapshot/events
POST	/api/v1/openclaw/approvals/{id}/resolve	approval resolution
GET	/api/v1/openclaw/activity	normalized recent Gateway events
GET	/api/v1/openclaw/models	models.list
GET	/api/v1/openclaw/agents	agents.list

Each read returns its own state, message, recovery action and observation time. Missing scopes and missing Gateway methods are distinct from disconnection. Mutations return an explicit ok/state/message/data/recovery/completedAt envelope instead of silently succeeding.

Frontend integration

The authenticated shell polls only the Nexus facade and exposes one shared OpenClaw status/recovery contract. The implemented operator paths are:

• Run Control: tasks, sessions, approvals, cron, events, inspector and confirmation dialogs;
• Dashboard: authoritative agent/session projection, focus tasks, runtime status, model patching and Iris chat through Nexus;
• Agents and Agent Detail: live OpenClaw agents and session state merged with Nexus-safe metadata;
• Models: provider-safe live catalog with availability and recovery reasons;
• Activity: OpenClaw runtime events combined with Nexus control-plane events;
• Calendar: live cron list and owner-confirmed cron.run;
• Notifications: live approval summary plus working notification actions;
• Security and Settings: connection, version, scope and trust-boundary diagnostics without secret values;
• Projects, Tasks, Memory, Docs and Incidents: explicit OpenClaw context and recovery links while preserving Nexus ownership of their domain state.

Iris chat is hidden by default, opens as a modal and keeps the dashboard space for live orchestration. Sending uses POST /api/v1/chat; the conversation ID is stable per browser. The former /chat route is intentionally absent.

Additional reliability fixes

• Initial authentication now shares an in-flight refresh between overlapping router guards. Direct authenticated route loads no longer race into /login.
• Authenticated post-login hydration refreshes operations/sidebar state.
• Task Board and live-SSE consumers validate snapshot shape before assignment and fall back to polling instead of blanking the route.
• Iris history uses stable timestamps in the QA fixture, preventing false duplicate-poll evidence.

Verification

Automated

Check	Result
pnpm test	3 files, 5 tests passed
pnpm build	Typecheck and Vite production build passed; 1886 modules
.tools/dotnet/dotnet.exe test backend-tests/Nexus.Api.Tests.csproj --configuration Release	201/201 passed
Gateway protocol/normalization tests	challenge, hello, errors, capabilities, tasks, cron, approvals and session-model patch covered
Frontend state tests	concurrent auth initialization, disconnected recovery and API failure covered

Operated browser paths

• all 17 authenticated routes loaded at 375, 768, 1024, 1440 and 1920 px;
• no document-level horizontal overflow or visible alert remained;
• Run Control node selection, cancel confirmation, approval resolution and cron execution worked;
• Activity and Models search/detail dialogs worked and closed with Escape;
• Task Board opened a real task detail;
• dashboard Iris chat loaded once, sent, received, closed and restored focus;
• the Iris agent session model changed through the typed facade;
• a notification marked read and routed to its target; mark-all-read cleared the unread count;
• the final browser console contained no warning or error entries.

The browser data came from scripts/qa/openclaw-ui-mock.mjs. Every response is labelled with X-Nexus-QA-Fixture, and the UI visibly reports QA SIMULATION; it is not live OpenClaw evidence.

Visual evidence

• Dashboard reference vs current
• Run Control mockup vs functional build
• All core pages contact sheet
• Run Control responsive contact sheet
• Route evaluation
• Design QA

Remaining production boundary

The next release-blocking proof is:

1. pair a backend device identity for the actual remote/container topology, or run Nexus in the documented direct-loopback topology;
2. pin the deployed Gateway version;
3. configure OpenAI exclusively inside OpenClaw;
4. run one credentialed flow Nexus -> OpenClaw session -> OpenAI -> OpenClaw result -> Nexus;
5. record provider/model evidence, an unauthorized negative case, reconnect recovery and an audited owner mutation.

Until this proof exists, Nexus is a tested control-plane implementation but not yet a verified replacement for every OpenClaw operational workflow.

Primary sources

• OpenClaw Gateway protocol
• Building an OpenClaw Gateway client
• OpenClaw operator scopes
• OpenClaw models
• OpenClaw background tasks
• OpenClaw cron operations
• OpenClaw tools invoke HTTP API
• OpenClaw Gateway troubleshooting