Summary

• Problem: The avatar storage used a single global localStorage key openclaw.control.assistant.v1, causing setting an avatar for one agent to overwrite it for all agents.
• Why now: Users with multiple agents (e.g. main, worker) cannot set different avatars for each agent. Setting an avatar for one agent silently overwrites the avatar for all other agents via the shared key.
• Outcome: Scope the localStorage key per agent ID: openclaw.control.assistant.v1:{agentId}. When clearing a scoped avatar, store null explicitly to prevent fallback to the global key. Include backward compatibility: existing global avatars are used as fallback when no agent-specific avatar exists.
• Out of scope: No changes to avatar upload, display, or server-side storage.
• Reviewer focus: Whether the localAssistantIdentityKey() function correctly scopes keys, whether the explicit null prevents legacy fallback, and whether the global fallback is preserved for new agents.

Linked context

Closes #90890

Real behavior proof

• Behavior or issue addressed: Setting avatar for one agent changes it for all agents; clearing a scoped avatar incorrectly falls back to the legacy global avatar -- [Bug]: You cannot give an avatar to a specific agent in settings #90890.
• Real environment tested: Windows 10, Node.js v22.22.3, vitest 4.1.7, local checkout on branch fix/90890-avatar-per-agent.
• Exact steps or command run after this patch: Ran npx vitest run ui/src/ui/controllers/assistant-identity.test.ts ui/src/ui/controllers/proof-avatar-per-agent.proof.test.ts --config test/vitest/vitest.ui.config.ts --reporter verbose. The proof test (proof-avatar-per-agent.proof.test.ts) imports and exercises the real loadLocalAssistantIdentity() and saveLocalAssistantIdentity() functions from ui/src/ui/storage.ts against an in-memory localStorage mock via vi.stubGlobal("localStorage", createStorageMock()). The regression test (assistant-identity.test.ts) exercises the real setAssistantAvatarOverride() controller function which delegates to those same storage functions.
• Evidence after fix:

  RUN  v4.1.7 D:/JavaUp/openclaw
  
  ✓ |ui| ui/src/ui/controllers/proof-avatar-per-agent.proof.test.ts > avatar storage per agent ID — real code proof (#90890) > Test 1: per-agent scoping — main and worker have independent avatars 4ms
  ✓ |ui| ui/src/ui/controllers/proof-avatar-per-agent.proof.test.ts > avatar storage per agent ID — real code proof (#90890) > Test 2: clear isolation — clearing main does not affect worker 1ms
  ✓ |ui| ui/src/ui/controllers/proof-avatar-per-agent.proof.test.ts > avatar storage per agent ID — real code proof (#90890) > Test 3: global fallback — new agent without scoped key falls back to global 0ms
  ✓ |ui| ui/src/ui/controllers/proof-avatar-per-agent.proof.test.ts > avatar storage per agent ID — real code proof (#90890) > Test 4: scoped clear blocks legacy global fallback (upgrade scenario) 1ms
  ✓ |ui| ui/src/ui/controllers/proof-avatar-per-agent.proof.test.ts > avatar storage per agent ID — real code proof (#90890) > Test 5: explicit null stored in scoped key to prevent fallback 0ms
  ✓ |ui| ui/src/ui/controllers/proof-avatar-per-agent.proof.test.ts > avatar storage per agent ID — real code proof (#90890) > Test 6: localStorage key naming — scoped keys use colon separator 1ms
  ✓ |ui| ui/src/ui/controllers/assistant-identity.test.ts > loadAssistantIdentity > ignores stale identity responses after the active session changes 6ms
  ✓ |ui| ui/src/ui/controllers/assistant-identity.test.ts > setAssistantAvatarOverride > persists the assistant avatar locally and mirrors the user avatar pattern 1ms
  ✓ |ui| ui/src/ui/controllers/assistant-identity.test.ts > setAssistantAvatarOverride > clears the local override 1ms
  ✓ |ui| ui/src/ui/controllers/assistant-identity.test.ts > setAssistantAvatarOverride > scopes avatar storage per agent ID (regression #90890) 1ms
  ✓ |ui| ui/src/ui/controllers/assistant-identity.test.ts > setAssistantAvatarOverride > falls back to global key when agent-specific key is not set 0ms
  ✓ |ui| ui/src/ui/controllers/assistant-identity.test.ts > setAssistantAvatarOverride > handles legacy global key after scoped clear (upgrade scenario) 1ms
  
  Test Files  2 passed (2)
       Tests  12 passed (12)
  

• Observed result after fix: All 12 tests pass across 2 test files. Per-agent scoping works: main and worker have independent avatars. Clearing one agent does not affect others. New agents without scoped keys fall back to the global key. Scoped clears store explicit {\"avatar\":null} to prevent legacy fallback. The setAssistantAvatarOverride controller correctly passes state.assistantAgentId to storage functions, and loadAssistantIdentity reads scoped local overrides.
• What was not tested: Live Control UI test with multiple agents in a running gateway (requires gateway setup with multiple agent configurations).

Tests and validation

• Regression: ui/src/ui/controllers/assistant-identity.test.ts -- 6/6 passed
• Proof: ui/src/ui/controllers/proof-avatar-per-agent.proof.test.ts -- 6/6 passed
• Total: 12/12 passed

Risk checklist

• userVisible: Yes (avatars now scoped per agent; legacy fallback behavior changed for scoped clears)
• configEnvMigration: No (backward compatible with global key)
• securityAuthNetwork: No
• Mitigation: Backward compatible; existing global avatars used as fallback for new agents. Scoped clears now store explicit null to prevent unexpected legacy fallback.