nexus/docs/agent-identity-architecture.md

Agent Identity Architecture (P4)

Status: ✅ Implemented (2026-07-13) Task: 4291d694-dd40-410d-b0d5-4742d334547a

Problem

Nexus needed agent identity data (id, name, role, sub-agents, model) for the board/bridge operations, but reading directly from /home/node/.openclaw/openclaw.json would expose secrets (gateway password, API keys, auth profiles, channel tokens).

Solution: Sanitized Agent Config File

Architecture

openclaw.json (full config, SECRETS)
    │
    ├── Deploy-time: jq extract → agents-sanitized.json (NO secrets)
    │   └── deploy-nexus.sh: extracts only {"agents": ...} from openclaw.json
    │
    ├── Manual sync: scripts/sync-agents-sanitized.mjs
    │   └── node scripts/sync-agents-sanitized.mjs --once
    │
    └── Nexus API reads: agents-sanitized.json (read-only mount in compose)
        ├── AgentService.LoadAgentConfigsAsync()
        ├── OpenClawGatewayClient.LoadAgentIdsFromConfig()
        └── AgentService.GetAllowedAgentIdsAsync()

Key Design Decisions

1. Single sanitized source: agents-sanitized.json contains ONLY the agents key (list + defaults) — no gateway, auth, channels, tools, plugins, etc.

2. Read-only mount: Compose mounts as :ro — no write access from the API container

3. No ACL dependency: No uid-1654 ACL needed; the sanitized file is root-owned and world-readable

4. Graceful fallback: If the sanitized file is missing, both AgentService and OpenClawGatewayClient fall back to hardcoded agent IDs from AgentIdentityCatalog

5. Auto-sync on deploy: The deploy pipeline (deploy-nexus.sh) regenerates the sanitized file from openclaw.json using jq in an alpine container

6. Manual sync available: scripts/sync-agents-sanitized.mjs provides on-demand and watch-mode sync

File Layout

File	Location	Purpose
openclaw.json	/home/node/.openclaw/openclaw.json	Full config with secrets (gateway only)
agents-sanitized.json	/home/node/.openclaw/agents-sanitized.json	Agents-only, no secrets
Compose mount	compose.yaml → API container	agents-sanitized.json:ro
Deploy sanitizer	.gitea/scripts/deploy-nexus.sh	jq extraction on deploy
Sync script	scripts/sync-agents-sanitized.mjs	Node.js manual/watch sync
Config path	backend/appsettings.json	AgentConfigPath key

Security Guarantees

• ✅ No password, token, secret, or api_key values in agents-sanitized.json
• ✅ API endpoints (/api/v1/agents, /api/v1/agents/{id}) return ZERO secrets
• ✅ Gateway bridge controller (/api/bridge/*) uses only agent IDs from sanitized config
• ✅ No direct openclaw.json reads in any C# code path
• ✅ Agent identity catalog (AgentIdentityCatalog) is a hardcoded fallback, not a primary source

Verification

# Check sanitized file has no secrets
curl -s http://nexus-api-1:8080/api/v1/agents \
  -H "X-Api-Key: <key>" | grep -i "password\|secret\|token\|apikey"
# Expected: no output

# Verify only "agents" key exists in sanitized file
python3 -c "
import json
with open('agents-sanitized.json') as f:
    data = json.load(f)
print(list(data.keys()))  # Should print ['agents']
"