nexus/docs/agent-identity-architecture.md

Agent identity architecture

Status: Live OpenClaw RPC authority implemented and verified on 2026-07-30. The former agents-sanitized.json design is retired.

Authority contract

OpenClaw is the sole runtime authority for agent identity, model assignment, workspace metadata and agent bootstrap files. Nexus does not copy that data into a second configuration and does not derive a host path from an agent ID.

OpenClaw Gateway
  agents.list
      |
      v
Nexus backend
  IOpenClawControlService
      |
      +--> /api/v1/agents
      +--> /api/v1/agents/{id}
      +--> Dashboard and allow-listed agent operations

OpenClaw Gateway
  agents.files.list/get/set
  agents.workspace.list/get
      |
      v
Nexus owner-only agent configuration facade

New OpenClaw agents therefore appear without a Compose change, deploy-time sanitizer or static fallback catalog.

Security properties

• The browser talks only to typed Nexus endpoints; it never receives Gateway credentials, provider credentials or raw OpenClaw configuration.
• agents.list supplies the current allow-list. A caller-provided agent ID is metadata after authentication, not identity proof.
• Supported bootstrap files use agents.files.*. Writes require owner, management consent, advertised capability, operator.admin, Idempotency-Key, expectedHash, pre-write re-read and post-write verification.
• Additional files use agents.workspace.* and remain read-only because the pinned OpenClaw contract has no safe arbitrary workspace-write RPC.
• Nexus never reads openclaw.json and never maps an agent ID to /mnt/workspace-{agentId}.
• The separate Memory, Docs and Incidents surfaces may retain one explicitly configured, confined Iris content root until equivalent safe OpenClaw RPCs exist. That bounded compatibility reader is not an agent-identity or per-agent-configuration source.

Retired design

The 2026-07-13 implementation generated and mounted agents-sanitized.json. It also depended on a static fallback catalog and required deployment synchronization. The 2026-07-30 RPC cutover removed these production dependencies:

• no AgentConfigPath;
• no sanitized-agent Compose mount;
• no deploy-time or watch-mode sanitizer;
• no hardcoded fallback as runtime authority; and
• no fixed workspace derivation.

Verification

The final 2026-07-30 backend suite passed 312/312 tests. Focused tests cover live inventory, nonstandard workspace metadata such as workspace-po, session model resolution, file hash conflicts, verified read-back and session-history fallback. Repository search found no remaining AgentConfigPath, agents-sanitized or /mnt/workspace-{agentId} dependency in production backend code or backend tests.

Canonical integration and release boundaries are documented in:

• docs/OPENCLAW_GATEWAY_CONNECTION.md
• docs/AGENT_FIRST_MISSION_CONTROL.md
• docs/audits/2026-07-30/openclaw-attach-adopt/IMPLEMENTATION_AND_ACCEPTANCE.md