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

```text
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`