AzuTear
81 lines
2.9 KiB
Markdown
81 lines
2.9 KiB
Markdown
# 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`
|