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.

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
• Gateway protocol
• Operator scopes
• Gateway configuration
• Agent workspace
• OpenClaw wizard
• Cron operations