fix(ui): scope local assistant avatar overrides per agent (#90890)

hanZeng-08 · hanZeng-08 · commit 70cf07eabeac · 2026-06-06T20:28:51.000+08:00
The Control UI stored the assistant avatar override under a single global localStorage key (openclaw.control.assistant.v1). As a result, every agent shared the same avatar: setting one agent's avatar overwrote all others. - Change loadLocalAssistantIdentity/saveLocalAssistantIdentity to accept an optional agentId and persist overrides under an agents map - Migrate legacy flat avatar entries on save (the old avatar is preserved as a fallback until the user saves a per-agent override) - Update loadAssistantIdentity and setAssistantAvatarOverride to pass the current agent id through to storage - Add tests proving main and worker agents can have independent avatars Test plan: - pnpm test ui/src/ui/controllers/assistant-identity.test.ts (5/5 pass) Closes #90890
diff --git a/ui/src/ui/controllers/assistant-identity.test.ts b/ui/src/ui/controllers/assistant-identity.test.ts
@@ -96,4 +96,63 @@ describe("setAssistantAvatarOverride", () => {
     expect(state.assistantAvatarReason).toBeNull();
     expect(loadLocalAssistantIdentity().avatar).toBeNull();
   });
+
+  it("scopes local avatar overrides per agent", () => {
+    const mainState: Parameters<typeof setAssistantAvatarOverride>[0] = {
+      assistantAgentId: "main",
+    };
+    const workerState: Parameters<typeof setAssistantAvatarOverride>[0] = {
+      assistantAgentId: "worker",
+    };
+
+    setAssistantAvatarOverride(mainState, "data:image/png;base64,main");
+    setAssistantAvatarOverride(workerState, "data:image/png;base64,worker");
+
+    expect(loadLocalAssistantIdentity("main").avatar).toBe("data:image/png;base64,main");
+    expect(loadLocalAssistantIdentity("worker").avatar).toBe("data:image/png;base64,worker");
+
+    setAssistantAvatarOverride(mainState, null);
+
+    expect(loadLocalAssistantIdentity("main").avatar).toBeNull();
+    expect(loadLocalAssistantIdentity("worker").avatar).toBe("data:image/png;base64,worker");
+  });
+
+  it("applies the local override only for the matching agent on load", async () => {
+    const mainState: Parameters<typeof setAssistantAvatarOverride>[0] = {
+      assistantAgentId: "main",
+    };
+    const workerState: Parameters<typeof setAssistantAvatarOverride>[0] = {
+      assistantAgentId: "worker",
+    };
+    setAssistantAvatarOverride(mainState, "data:image/png;base64,main");
+    setAssistantAvatarOverride(workerState, "data:image/png;base64,worker");
+
+    const request = vi.fn().mockResolvedValue({
+      agentId: "main",
+      name: "Main",
+      avatar: "server-main.png",
+    });
+    const state: Parameters<typeof loadAssistantIdentity>[0] = {
+      client: { request } as never,
+      connected: true,
+      sessionKey: "agent:main:main",
+      assistantName: "Main",
+      assistantAvatar: null,
+      assistantAgentId: "main",
+    };
+
+    await loadAssistantIdentity(state);
+    expect(state.assistantAvatar).toBe("data:image/png;base64,main");
+
+    request.mockResolvedValue({
+      agentId: "worker",
+      name: "Worker",
+      avatar: "server-worker.png",
+    });
+    state.sessionKey = "agent:worker:main";
+    state.assistantAgentId = "worker";
+
+    await loadAssistantIdentity(state);
+    expect(state.assistantAvatar).toBe("data:image/png;base64,worker");
+  });
 });
diff --git a/ui/src/ui/controllers/assistant-identity.ts b/ui/src/ui/controllers/assistant-identity.ts
@@ -68,7 +68,9 @@ export async function loadAssistantIdentity(
     state.assistantAvatarReason = normalized.avatarReason ?? null;
     state.assistantAgentId = normalized.agentId ?? null;
     // Local override always wins — same pattern as the user avatar.
-    const localAvatar = loadLocalAssistantIdentity().avatar;
+    // Scope the override to the current agent so different agents can have
+    // different avatars without clobbering each other.
+    const localAvatar = loadLocalAssistantIdentity(normalized.agentId ?? null).avatar;
     if (localAvatar) {
       state.assistantAvatar = localAvatar;
       state.assistantAvatarSource = localAvatar;
@@ -81,10 +83,10 @@ export async function loadAssistantIdentity(
 }
 
 export function setAssistantAvatarOverride(
-  state: AssistantAvatarOverrideState,
+  state: AssistantAvatarOverrideState & { assistantAgentId?: string | null },
   avatar: string | null,
 ) {
-  saveLocalAssistantIdentity({ avatar });
+  saveLocalAssistantIdentity({ avatar }, state.assistantAgentId ?? null);
   if (avatar) {
     state.assistantAvatar = avatar;
     state.assistantAvatarSource = avatar;
diff --git a/ui/src/ui/storage.ts b/ui/src/ui/storage.ts
@@ -350,28 +350,76 @@ export function saveLocalUserIdentity(next: LocalUserIdentity) {
 
 export type LocalAssistantIdentity = { avatar: string | null };
 
-export function loadLocalAssistantIdentity(): LocalAssistantIdentity {
+type PersistedLocalAssistantIdentity = {
+  // Legacy flat avatar stored before per-agent isolation.
+  avatar?: string | null;
+  // Per-agent avatar overrides. Key is the normalized agent id.
+  agents?: Record<string, LocalAssistantIdentity>;
+};
+
+export function loadLocalAssistantIdentity(agentId?: string | null): LocalAssistantIdentity {
   const storage = getSafeLocalStorage();
+  const normalizedAgentId = normalizeOptionalString(agentId) ?? "main";
   try {
     const raw = storage?.getItem(LOCAL_ASSISTANT_IDENTITY_KEY);
     if (!raw) {
       return { avatar: null };
     }
-    const parsed = JSON.parse(raw) as Partial<LocalAssistantIdentity>;
-    return { avatar: typeof parsed.avatar === "string" ? parsed.avatar : null };
+    const parsed = JSON.parse(raw) as Partial<PersistedLocalAssistantIdentity>;
+    // Per-agent storage takes precedence.
+    if (parsed.agents && typeof parsed.agents === "object") {
+      const agentEntry = parsed.agents[normalizedAgentId];
+      if (agentEntry && typeof agentEntry.avatar === "string") {
+        return { avatar: agentEntry.avatar };
+      }
+    }
+    // Legacy flat fallback: migrate on save, but for now treat the legacy
+    // avatar as belonging to the requested agent so existing users do not
+    // suddenly lose their override.
+    if (typeof parsed.avatar === "string") {
+      return { avatar: parsed.avatar };
+    }
+    return { avatar: null };
   } catch {
     return { avatar: null };
   }
 }
 
-export function saveLocalAssistantIdentity(next: LocalAssistantIdentity) {
+export function saveLocalAssistantIdentity(next: LocalAssistantIdentity, agentId?: string | null) {
   const storage = getSafeLocalStorage();
+  const normalizedAgentId = normalizeOptionalString(agentId) ?? "main";
   try {
+    let parsed: PersistedLocalAssistantIdentity = {};
+    try {
+      const raw = storage?.getItem(LOCAL_ASSISTANT_IDENTITY_KEY);
+      if (raw) {
+        parsed = JSON.parse(raw) as PersistedLocalAssistantIdentity;
+      }
+    } catch {
+      // ignore parse errors; start fresh
+    }
+
+    const nextAgents: Record<string, LocalAssistantIdentity> =
+      parsed.agents && typeof parsed.agents === "object" ? { ...parsed.agents } : {};
+
     if (!next.avatar) {
+      delete nextAgents[normalizedAgentId];
+    } else {
+      nextAgents[normalizedAgentId] = { avatar: next.avatar };
+    }
+
+    const persisted: PersistedLocalAssistantIdentity = {
+      ...parsed,
+      agents: nextAgents,
+    };
+    // Once migrated to per-agent storage, drop the legacy flat key.
+    delete persisted.avatar;
+
+    if (Object.keys(persisted.agents ?? {}).length === 0) {
       storage?.removeItem(LOCAL_ASSISTANT_IDENTITY_KEY);
       return;
     }
-    storage?.setItem(LOCAL_ASSISTANT_IDENTITY_KEY, JSON.stringify({ avatar: next.avatar }));
+    storage?.setItem(LOCAL_ASSISTANT_IDENTITY_KEY, JSON.stringify(persisted));
   } catch {
     // best-effort — quota exceeded or security restrictions should not
     // prevent in-memory identity updates from being applied
