nexus/docs/audits/2026-07-30/openclaw-attach-adopt/IMPLEMENTATION_AND_ACCEPTANCE.md

# Nexus OpenClaw Attach & Adopt — implementation and acceptance

**Date:** 2026-07-30
**Scope:** local Nexus working tree; no commit, push, deployment or VPS write
**Status:** implemented locally; final automated/browser suite pending entry;
production release blocked

## Outcome

Nexus now has a coherent, agent-first path for connecting one OpenClaw
instance, adopting its live inventory without copying Runtime data, and
deliberately elevating from read-only to management. The same typed boundary
now supplies agent files, read-only workspace content, schema-driven
configuration, cron lifecycle and sanitized model authentication status.

This is not a production-readiness claim. The pinned OpenClaw `2026.7.1`
client registry does not yet support the external Nexus-/Generic-Operator
identity required by this integration. Real pairing, scope upgrade, live test
mutations and a complete OpenAI execution remain mandatory blockers.

## Authority contract

| State | Authority |
|---|---|
| Users, roles, projects, product tasks, approvals and Nexus audit | Nexus |
| Agents, bootstrap/workspace files, OpenClaw config, cron, models, sessions, channels and nodes | OpenClaw |
| Model execution and provider secrets | OpenAI through OpenClaw |
| Connection/adoption metadata and local management consent | Nexus `primary` profile |

Adoption stores no agent-file content, cron definition, provider credential,
model configuration, channel or node. OpenClaw remains the source of truth and
Nexus refreshes these resources through advertised RPCs.

## Implemented setup contract

### Single persisted profile

The EF-backed `primary` profile stores the normalized endpoint,
discovery source, required version, optional TLS pin, adoption state,
management consent, capability hash, timestamps and an optimistic concurrency
version. Adoption returns a live inventory snapshot but does not persist its
resource contents.

Device private key and device token remain in the server-side device store.
Tokens are bound to endpoint, TLS fingerprint, role and scopes. OpenAI keys,
Gateway passwords, bootstrap token plaintext and provider secrets are not
stored in the profile or returned to the browser.

### Owner-only API

| Method | Route | Result |
|---|---|---|
| `GET` | `/api/v1/openclaw/setup` | Current setup, trust, pairing, adoption and management state |
| `POST` | `/api/v1/openclaw/setup/discover` | Only known candidates; optional explicit mDNS |
| `POST` | `/api/v1/openclaw/setup/probe` | Transport, TLS, version, identity and capability proof |
| `POST` | `/api/v1/openclaw/setup/attach` | Transient bootstrap credential and `operator.read` attachment |
| `POST` | `/api/v1/openclaw/setup/verify` | Re-check pairing, endpoint, device, scopes and capabilities |
| `POST` | `/api/v1/openclaw/setup/adopt` | Return live inventory and persist adoption/capability metadata without copying resources |
| `POST` | `/api/v1/openclaw/setup/management` | Deliberate scope-upgrade request and local management gate |
| `DELETE` | `/api/v1/openclaw/setup/connection` | Confirmed detach of profile, socket and bound token |

All routes require the owner role. Mutation routes are rate-limited and use
profile concurrency checks where applicable. Wizard Gateway mutations
additionally require an Idempotency Key and correlation context; resource
mutation audit is described in the sections below.

### Discovery, transport and secrets

- Discovery is limited to a configured endpoint,
  `openclaw-gateway:18789`, loopback, `host.docker.internal`, and expressly
  requested mDNS. The current build reports mDNS as unsupported and performs no
  network scan. There is no subnet scan and no Docker-socket access.
- External endpoints require `wss://` and a confirmed certificate
  fingerprint. Clear `ws://` is limited to loopback or an explicitly allowed
  internal Docker topology.
- A bootstrap token can be submitted through a masked owner field or a
  server-side SecretRef. It remains in memory only until the Device Token is
  issued.
- Initial adoption rejects an already admin-scoped connection. Management
  begins as a separate scope upgrade and requires renewed pairing approval.
- Detach clears the persisted profile, local management gate and matching
  Device Token, and closes the connector. A separately configured server
  bootstrap secret must still be revoked at its own source.

### External client identity gate

Nexus uses `nexus` as its intended external identity and does not imitate
OpenClaw's reserved `gateway-client/backend`, CLI or Control UI identities.
`OPENCLAW_EXTERNAL_CLIENT_ID_SUPPORTED` therefore defaults to `false`.
Discovery and UI can explain the blocker, but productive Attach/Adopt remains
blocked until a pinned OpenClaw version officially registers the external
identity and passes the contract suite.

## Implemented agent-first resource management

### Agents and files

- Agent inventory comes from `agents.list`; newly created OpenClaw agents no
  longer require a Nexus Compose edit or static sanitized inventory.
- File tabs are generated from `agents.files.list`.
- `agents.files.get/set` supplies and mutates the supported bootstrap files:
  `AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`,
  `HEARTBEAT.md`, `BOOTSTRAP.md` and optional `MEMORY.md`.
- Every write carries `content`, `expectedHash` and `Idempotency-Key`. Nexus
  re-reads before the mutation, rejects drift with `409`, writes through
  OpenClaw and verifies the new content through a second read.
- The success copy is limited to “saved and read back”; no unconfirmed hot
  reload is claimed.
- Extra files such as `DREAMS.md` or `memory/YYYY-MM-DD.md` are browsable
  through `agents.workspace.list/get` and remain read-only because the pinned
  OpenClaw contract has no safe arbitrary workspace-write RPC.
- The old `/api/v1/agents/{id}/config*` endpoints remain temporarily as
  owner-only compatibility adapters to the live RPC implementation.

Standing Orders are maintained in a controlled `AGENTS.md` section covering
goals, triggers, permitted actions, approval boundaries, escalation and
verify/report rules.

### OpenClaw configuration

Settings uses `config.schema.lookup`, `config.get` and `config.patch` rather
than raw host-file writes. Edits include `baseHash`, diff preview and explicit
`replacePaths`. A stale snapshot is rejected, a successful patch is read back,
and secret values are never projected to the browser.

### Cron lifecycle

OpenClaw remains the only cron data source. Nexus adds typed contracts for:

- paginated list and detail;
- paginated run history;
- create and hash-guarded patch;
- enable/disable through patch;
- delete; and
- immediate run with returned `runId` correlation.

A force run is displayed as queued. Only authoritative `cron.runs` data
determines success or failure. Mutations require owner, advertised RPC,
persisted `ManagementEnabled`, `operator.admin`, rate limit, audit and
Idempotency Key. Patch, delete and force run also require the current job hash;
create has no pre-existing resource hash.

Command payloads and `on-exit` schedules remain blocked by default through
`AllowCommandCron=false`. Delivery destinations are masked in collections,
logs and audit; full values belong only in the owner detail/edit context.
The unsafe legacy Dashboard-to-Gateway delete path no longer performs cron
deletion.

### Models auth status

`GET /api/v1/openclaw/models/auth-status` projects `models.authStatus` into a
browser-safe provider summary. It does not expose auth-profile IDs, e-mail
addresses, credentials, billing/usage windows or secret-bearing provider
payloads. OpenClaw `2026.7.1` does not provide all desired provenance fields;
Nexus leaves unavailable provenance empty rather than inventing it.

### Official OpenClaw wizard

Nexus renders the official `wizard.start`, `wizard.next`, `wizard.status` and
`wizard.cancel` protocol through owner-only setup routes. It supports notes,
selection, text, confirmation, multi-selection, progress, actions, device
codes and external links.

The backend requires an active connection, advertised method,
`operator.admin` and local management consent. It starts only the setup flow
with daemon installation disabled, redacts sensitive steps and rejects secret
answers from browser fields. Nexus does not install OpenClaw, perform SSH
bootstrap, or automatically run migrations or `doctor --fix`.

## Legacy filesystem boundary

The Attach & Adopt resource path does not derive workspaces as
`/mnt/workspace-{agentId}` and does not use `agents-sanitized.json` as agent
authority. The same implementation checkpoint removed those production
dependencies after RPC parity. Final repository review found no remaining
`AgentConfigPath`, `agents-sanitized` or fixed per-agent workspace derivation
in production backend code or backend tests.

The separate Nexus Memory/Docs/Incidents compatibility surfaces may retain one
explicitly configured, confined Iris content root until their own OpenClaw RPC
migration. That bounded content reader must not be used to infer live agents or
map an agent ID to a host path.

## UI contract

- Settings is the owner-only Setup Center:
  Discover → Probe → Pair read-only → Inventory → Adopt → optional Management.
- Agents uses live file tabs, dirty-state protection, hash-conflict recovery,
  read-only workspace browsing and Standing Orders.
- Calendar provides list/detail, create/edit, enable/disable, delete, queued
  run and paginated history.
- Security exposes device, endpoint trust, scopes and capability boundaries.
- Models shows only catalog data and sanitized `models.authStatus`.
- Loading, empty, blocked, incompatible, conflict and failure states remain
  explicit. A failed RPC is never converted into a plausible empty list.

The responsive and accessibility proof targets are defined in
[Structural Proof Preflight](STRUCTURAL_PROOF_PREFLIGHT.md).

## Final local verification

The following checks were rerun against the combined working tree on
2026-07-30 after the RPC cutover, Legacy-FS cleanup, QA-fixture expansion and
the final Settings layout correction.

| Check | Required command/evidence | Final result |
|---|---|---|
| Backend | `.tools\dotnet\dotnet.exe test backend-tests/Nexus.Api.Tests.csproj --configuration Release` using the bundled .NET 10 SDK | **Passed: 312/312, 0 skipped** |
| Frontend typecheck | `pnpm typecheck` in `frontend/` | **Passed** |
| Frontend unit tests | `pnpm test` in `frontend/` | **Passed: 6/6 files, 12/12 tests** |
| Frontend production build | `pnpm build` in `frontend/` | **Passed: 1,914 modules**; existing 500 kB chunk advisory remains |
| Working-tree hygiene | `git diff --check` | **Passed**; Windows line-ending notices only |
| Browser functional QA | Settings setup/discovery and `wizard.*`, config patch/read-back, agent file write/read-back, read-only workspace, Calendar create/detail/history/run correlation, Models auth detail and Iris modal through the controlled mock | **Passed** |
| Responsive/overflow QA | All 18 authenticated core routes at 375 and 1440 CSS px; Dashboard, Settings, Agent Detail, Calendar and Run Control additionally at 768, 1024 and 1920 CSS px | **Passed: zero document overflow** |
| Console/accessibility QA | Named controls and dialogs, focus transfer, status announcements, modal close and browser console | **Passed: no console warnings or errors** |

The controlled mock is explicitly synthetic evidence. It verifies Nexus UI
contracts and interaction semantics without representing a successful live
OpenClaw connection or authorizing any VPS mutation.

## Production blockers and separate live acceptance

Production readiness remains **blocked** until all of the following are
demonstrated:

1. The pinned OpenClaw release officially supports the external Nexus or
   generic operator Client ID.
2. Bao's explicitly scoped OpenClaw accepts the real read-only Pairing and the
   later management Scope Upgrade.
3. The previously observed inventory expectation of 9 agents and 7 cron jobs
   is reverified read-only without inspecting or enumerating resources outside
   Bao's scope.
4. Hash-conflict and verified write/read-back tests succeed on explicitly
   named disposable agent-file, config and cron test objects.
5. A real `Nexus -> OpenClaw -> OpenAI -> Nexus` run proves OpenAI as primary
   provider without exposing prompt, token, delivery target or credential
   data.
6. Reconnect, missing method, version drift, denied scope, `{ok:false}`,
   timeout, stale write, idempotent replay and uncertain-outcome recovery pass
   in the target topology.

No live mutation, pairing approval, OpenClaw patch, deployment or access to
out-of-scope resources was authorized or performed by this implementation
checkpoint.

## Remaining product work

- Official external client identity and real topology acceptance.
- Agent create/enable/disable/restart/delete and template workflows.
- Tool catalog, effective rights, policies, channels and nodes.
- Safe arbitrary workspace mutation if OpenClaw adds a suitable RPC.
- Full provider/model policy editing, budgets, evals and authoritative usage.
- Cron templates plus retry, missed-run and alerting policies.
- Transactional shared idempotency/audit storage before multiple API writers.
- Full OpenAI E2E, recovery, security and release gates.

## Primary references

- [Stable OpenClaw `2026.7.1` client registry](https://github.com/openclaw/openclaw/blob/v2026.7.1/packages/gateway-protocol/src/client-info.ts)
- [Gateway protocol](https://github.com/openclaw/openclaw/blob/v2026.7.1/docs/gateway/protocol.md)
- [Operator scopes](https://docs.openclaw.ai/gateway/operator-scopes)
- [Gateway configuration](https://docs.openclaw.ai/gateway/configuration)
- [Agent workspace](https://github.com/openclaw/openclaw/blob/v2026.7.1/docs/concepts/agent-workspace.md)
- [OpenClaw wizard](https://docs.openclaw.ai/reference/wizard)
- [Cron operations](https://docs.openclaw.ai/cli/cron)