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

```text
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](dashboard-reference-vs-current.png)
- [Run Control mockup vs functional build](run-control-mock-vs-current.png)
- [All core pages contact sheet](core-pages-contact-sheet.png)
- [Run Control responsive contact sheet](run-control-responsive-contact-sheet.png)
- [Route evaluation](ROUTE_EVALUATION.md)
- [Design QA](design-qa.md)

## 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](https://docs.openclaw.ai/gateway/protocol)
- [Building an OpenClaw Gateway client](https://docs.openclaw.ai/gateway/clients)
- [OpenClaw operator scopes](https://docs.openclaw.ai/gateway/operator-scopes)
- [OpenClaw models](https://docs.openclaw.ai/models)
- [OpenClaw background tasks](https://docs.openclaw.ai/automation/tasks)
- [OpenClaw cron operations](https://docs.openclaw.ai/cli/cron)
- [OpenClaw tools invoke HTTP API](https://docs.openclaw.ai/gateway/tools-invoke-http-api)
- [OpenClaw Gateway troubleshooting](https://docs.openclaw.ai/gateway/troubleshooting)