diff --git a/desktop/renderer/env.d.ts b/desktop/renderer/env.d.ts
index cbd7be7..0173d40 100644
--- a/desktop/renderer/env.d.ts
+++ b/desktop/renderer/env.d.ts
@@ -121,7 +121,7 @@ interface OpenClawAPI {
   };
   settings: {
     get(): Promise<AppSettings>;
-    set(key: string, value: any): Promise<void>;
+    set<K extends keyof AppSettings>(key: K, value: AppSettings[K]): Promise<void>;
   };
   updates: {
     check(): Promise<UpdateCheckResult>;
@@ -167,6 +167,9 @@ interface OpenClawAPI {
   };
   agents: {
     list(): Promise<{ agents?: { id: string; name: string; description?: string }[] }>;
+    add(agentId: string): Promise<{
+      agents: { id: string; name: string; description?: string }[];
+    }>;
   };
   channels: {
     list(): Promise<{
diff --git a/desktop/renderer/src/App.vue b/desktop/renderer/src/App.vue
index e5e9d3c..bc7f431 100644
--- a/desktop/renderer/src/App.vue
+++ b/desktop/renderer/src/App.vue
@@ -469,6 +469,7 @@ onMounted(async () => {
     }
     // Fetch scheduled tasks now that gateway is connected
     taskStore.fetchTasks();
+    agentStore.fetchAgents();
     // Refresh WeChat login status (important after gateway restart)
     gateway.refreshWeixinStatus();
   });
@@ -503,6 +504,7 @@ onMounted(async () => {
       sessionStore.reconcileEmptySessions(chatStore.sessionKey, "main");
       sessionStore.ensureSession(chatStore.sessionKey, "main");
       chatStore.loadHistory();
+      agentStore.fetchAgents();
     }
   });
 
diff --git a/desktop/renderer/src/components/agent/AgentCard.vue b/desktop/renderer/src/components/agent/AgentCard.vue
index e505b47..5e0f146 100644
--- a/desktop/renderer/src/components/agent/AgentCard.vue
+++ b/desktop/renderer/src/components/agent/AgentCard.vue
@@ -13,10 +13,8 @@
       <div v-if="agent.tags?.length" class="agent-card-tags">
         <span v-for="tag in agent.tags" :key="tag" class="agent-card-tag">{{ tag }}</span>
       </div>
-      <span v-if="agent.isAdded" class="agent-card-added-text" @click="$emit('toggle', agent.id)">{{
-        t("agentMarket.added")
-      }}</span>
-      <button v-else class="agent-card-action" @click="$emit('toggle', agent.id)">
+      <span v-if="agent.isAdded" class="agent-card-added-text">{{ t("agentMarket.added") }}</span>
+      <button v-else class="agent-card-action" @click="$emit('add', agent.id)">
         <IconPlus :size="14" />
         {{ t("agentMarket.add") }}
       </button>
@@ -35,7 +33,7 @@ defineProps<{
 }>();
 
 defineEmits<{
-  toggle: [agentId: string];
+  add: [agentId: string];
 }>();
 </script>
 
@@ -85,7 +83,6 @@ defineEmits<{
   font-size: 12px;
   font-weight: 600;
   color: var(--success);
-  cursor: pointer;
 }
 
 .agent-card-avatar {
diff --git a/desktop/renderer/src/i18n/en-US.ts b/desktop/renderer/src/i18n/en-US.ts
index f29267a..a34c47a 100644
--- a/desktop/renderer/src/i18n/en-US.ts
+++ b/desktop/renderer/src/i18n/en-US.ts
@@ -732,11 +732,27 @@ export default {
   "agentMarket.pageTitle": "Popular Agents",
   "agentMarket.add": "Add",
   "agentMarket.added": "Added",
+  "agentMarket.addFailed": "Couldn't add the agent to OpenClaw. Please try again.",
 
   // ── Agent: quick tasks expand ──
   "agent.quickTasks": "Quick Tasks",
 
-  // ── Agents (mock data) ──
+  // ── Agents ──
+  "agent.masterArchive.name": "Master Archive",
+  "agent.masterArchive.desc": "Local file organization, batch conversion & document digests",
+  "agent.masterArchive.tag.1": "File Organization",
+  "agent.masterArchive.tag.2": "Batch Conversion",
+  "agent.masterArchive.tag.3": "Document Digests",
+  "agent.masterArchive.task.1.title": "Convert the Word files in this folder to PDF",
+  "agent.masterArchive.task.1.desc":
+    "Batch-convert matching documents while preserving the originals.",
+  "agent.masterArchive.task.2.title": "Organize this folder - show me the plan first",
+  "agent.masterArchive.task.2.desc":
+    "Inventory the files and preview a safe folder structure before moving anything.",
+  "agent.masterArchive.task.3.title": "Extract deadlines and action items from these documents",
+  "agent.masterArchive.task.3.desc":
+    "Consolidate owners, due dates, and source references into a clean checklist.",
+
   "agent.coder.name": "Coder",
   "agent.coder.desc": "Code development, debugging & code review",
   "agent.coder.tag.1": "Development",
diff --git a/desktop/renderer/src/i18n/zh-CN.ts b/desktop/renderer/src/i18n/zh-CN.ts
index 16a6271..6ad5bb9 100644
--- a/desktop/renderer/src/i18n/zh-CN.ts
+++ b/desktop/renderer/src/i18n/zh-CN.ts
@@ -705,11 +705,24 @@ export default {
   "agentMarket.pageTitle": "热门 Agent",
   "agentMarket.add": "添加",
   "agentMarket.added": "已添加",
+  "agentMarket.addFailed": "无法将 Agent 添加到 OpenClaw，请重试。",
 
   // ── Agent: quick tasks expand ──
   "agent.quickTasks": "快捷任务",
 
-  // ── Agents (mock data) ──
+  // ── Agents ──
+  "agent.masterArchive.name": "归藏大师",
+  "agent.masterArchive.desc": "本地文件整理、批量转换与文档摘要",
+  "agent.masterArchive.tag.1": "文件整理",
+  "agent.masterArchive.tag.2": "批量转换",
+  "agent.masterArchive.tag.3": "文档摘要",
+  "agent.masterArchive.task.1.title": "把这个文件夹里的 Word 批量转成 PDF",
+  "agent.masterArchive.task.1.desc": "保留原文件，并批量转换符合条件的文档。",
+  "agent.masterArchive.task.2.title": "整理这个文件夹，先给我看方案",
+  "agent.masterArchive.task.2.desc": "先盘点文件并预览安全的目录结构，确认后再移动。",
+  "agent.masterArchive.task.3.title": "汇总这些文档中的截止日期和待办",
+  "agent.masterArchive.task.3.desc": "整理负责人、截止日期和来源，生成清晰的任务清单。",
+
   "agent.coder.name": "程序猿",
   "agent.coder.desc": "代码开发、调试与代码审查",
   "agent.coder.tag.1": "代码开发",
diff --git a/desktop/renderer/src/main.ts b/desktop/renderer/src/main.ts
index 290745a..7f1cd84 100644
--- a/desktop/renderer/src/main.ts
+++ b/desktop/renderer/src/main.ts
@@ -36,9 +36,27 @@ if (isBrowserDev) {
       generateSnapshot: noopAsync,
     },
     settings: {
-      get: () => Promise.resolve(null),
+      get: () =>
+        Promise.resolve({
+          language: "en-US",
+          autoStart: false,
+          startMinimized: false,
+          themeMode: "light",
+          accentColor: "#1e1f25",
+          privacyLevel: "balanced",
+        }),
       set: noopAsync,
     },
+    agents: {
+      list: () => Promise.resolve({ agents: [] }),
+      add: (agentId: string) =>
+        Promise.resolve({
+          agents: [
+            { id: "main", name: "Assistant" },
+            { id: agentId, name: agentId },
+          ],
+        }),
+    },
     updates: {
       check: () =>
         Promise.resolve({
diff --git a/desktop/renderer/src/stores/agents.test.ts b/desktop/renderer/src/stores/agents.test.ts
new file mode 100644
index 0000000..9651630
--- /dev/null
+++ b/desktop/renderer/src/stores/agents.test.ts
@@ -0,0 +1,92 @@
+import { createPinia, setActivePinia } from "pinia";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { setLocale } from "@/i18n";
+import { useAgentStore } from "./agents";
+
+describe("agent store", () => {
+  const agentsList = vi.fn();
+  const agentsAdd = vi.fn();
+
+  beforeEach(() => {
+    setActivePinia(createPinia());
+    setLocale("en-US");
+    agentsList
+      .mockReset()
+      .mockResolvedValue({ agents: [{ id: "main", name: "Assistant" }] });
+    agentsAdd.mockReset();
+    window.openclaw = {
+      agents: { list: agentsList, add: agentsAdd },
+    } as unknown as typeof window.openclaw;
+  });
+
+  it("shows only the OpenClaw roster in the sidebar", async () => {
+    const store = useAgentStore();
+
+    expect(store.agents.map((agent) => agent.id)).toEqual(["main"]);
+
+    agentsList.mockResolvedValueOnce({
+      agents: [
+        { id: "main", name: "Assistant" },
+        { id: "custom", name: "Custom Agent" },
+      ],
+    });
+    await store.fetchAgents();
+    expect(store.agents.map((agent) => agent.id)).toEqual(["main", "custom"]);
+  });
+
+  it("adds Master Archive to OpenClaw before showing it in the sidebar", async () => {
+    const store = useAgentStore();
+    const marketAgent = store.marketAgents.find(
+      (entry) => entry.id === "master-archive",
+    );
+
+    expect(marketAgent).toMatchObject({
+      name: "Master Archive",
+      isAdded: false,
+      tags: ["File Organization", "Batch Conversion", "Document Digests"],
+    });
+    expect(marketAgent?.quickTasks).toHaveLength(3);
+
+    agentsAdd.mockResolvedValueOnce({
+      agents: [
+        { id: "main", name: "Assistant" },
+        { id: "master-archive", name: "Master Archive" },
+      ],
+    });
+    await store.addAgent("master-archive");
+
+    expect(agentsAdd).toHaveBeenCalledWith("master-archive");
+    expect(store.agents.map((agent) => agent.id)).toEqual([
+      "main",
+      "master-archive",
+    ]);
+    expect(
+      store.marketAgents.find((agent) => agent.id === "master-archive")?.isAdded,
+    ).toBe(true);
+  });
+
+  it("keeps the roster unchanged when Add fails", async () => {
+    const store = useAgentStore();
+    agentsAdd.mockRejectedValueOnce(new Error("Gateway restart failed"));
+
+    await expect(store.addAgent("master-archive")).rejects.toThrow(
+      "Gateway restart failed",
+    );
+    expect(store.agents.map((agent) => agent.id)).toEqual(["main"]);
+    expect(
+      store.marketAgents.find((agent) => agent.id === "master-archive")?.isAdded,
+    ).toBe(false);
+  });
+
+  it("preserves the last real roster when refresh fails", async () => {
+    const store = useAgentStore();
+    agentsList.mockResolvedValueOnce({
+      agents: [{ id: "custom", name: "Custom Agent" }],
+    });
+    await store.fetchAgents();
+    agentsList.mockRejectedValueOnce(new Error("Gateway not connected"));
+    await store.fetchAgents();
+
+    expect(store.agents.map((agent) => agent.id)).toEqual(["custom"]);
+  });
+});
diff --git a/desktop/renderer/src/stores/agents.ts b/desktop/renderer/src/stores/agents.ts
index c48c660..ed3ea65 100644
--- a/desktop/renderer/src/stores/agents.ts
+++ b/desktop/renderer/src/stores/agents.ts
@@ -1,6 +1,7 @@
 import { defineStore } from "pinia";
 import { ref, computed } from "vue";
 import { t, locale } from "../i18n";
+import { AGENT_CATALOG, type AgentCatalogEntry } from "../../../src/agent-catalog";
 
 export interface QuickTask {
   title: string;
@@ -18,16 +19,10 @@ export interface Agent {
   isAdded?: boolean;
 }
 
-/** Raw agent definition — stores i18n keys, not translated strings. */
-interface AgentDef {
+interface RuntimeAgent {
   id: string;
-  nameKey: string;
-  descKey: string;
-  avatar: string;
-  image: string;
-  tagKeys: string[];
-  taskKeys: { titleKey: string; descKey: string }[];
-  isAdded: boolean;
+  name: string;
+  description?: string;
 }
 
 // Static import of avatar assets
@@ -42,180 +37,112 @@ function getAvatarUrl(filename: string): string {
   return avatarModules[key] || "";
 }
 
-/** Resolve an AgentDef into an Agent with translated strings (reactive via computed). */
-function resolveAgent(def: AgentDef): Agent {
+/** Resolve a catalog entry into an Agent with translated strings. */
+function resolveCatalogAgent(def: AgentCatalogEntry, isAdded: boolean): Agent {
   return {
     id: def.id,
     name: t(def.nameKey),
     description: t(def.descKey),
-    avatar: def.avatar,
-    image: def.image,
+    avatar: getAvatarUrl(def.avatar),
+    image: getAvatarUrl(def.image),
     tags: def.tagKeys.map((k) => t(k)),
     quickTasks: def.taskKeys.map((tk) => ({
       title: t(tk.titleKey),
       desc: t(tk.descKey),
     })),
-    isAdded: def.isAdded,
+    isAdded,
   };
 }
 
-const AGENT_DEFS: AgentDef[] = [
-  {
-    id: "main",
-    nameKey: "store.defaultAgent",
-    descKey: "store.defaultAgentDesc",
-    avatar: getAvatarUrl("normal.png"),
-    image: getAvatarUrl("normal.png"),
-    tagKeys: [],
-    taskKeys: [
-      { titleKey: "agent.main.task.1.title", descKey: "agent.main.task.1.desc" },
-      { titleKey: "agent.main.task.2.title", descKey: "agent.main.task.2.desc" },
-      { titleKey: "agent.main.task.3.title", descKey: "agent.main.task.3.desc" },
-    ],
-    isAdded: true,
-  },
-  {
-    id: "coder",
-    nameKey: "agent.coder.name",
-    descKey: "agent.coder.desc",
-    avatar: getAvatarUrl("程序猿.png"),
-    image: getAvatarUrl("Coder.png"),
-    tagKeys: ["agent.coder.tag.1", "agent.coder.tag.2", "agent.coder.tag.3"],
-    taskKeys: [
-      { titleKey: "agent.coder.task.1.title", descKey: "agent.coder.task.1.desc" },
-      { titleKey: "agent.coder.task.2.title", descKey: "agent.coder.task.2.desc" },
-      { titleKey: "agent.coder.task.3.title", descKey: "agent.coder.task.3.desc" },
-    ],
-    isAdded: true,
-  },
-  {
-    id: "painter",
-    nameKey: "agent.painter.name",
-    descKey: "agent.painter.desc",
-    avatar: getAvatarUrl("梵高.png"),
-    image: getAvatarUrl("Painter.png"),
-    tagKeys: ["agent.painter.tag.1", "agent.painter.tag.2", "agent.painter.tag.3"],
-    taskKeys: [
-      { titleKey: "agent.painter.task.1.title", descKey: "agent.painter.task.1.desc" },
-      { titleKey: "agent.painter.task.2.title", descKey: "agent.painter.task.2.desc" },
-      { titleKey: "agent.painter.task.3.title", descKey: "agent.painter.task.3.desc" },
-    ],
-    isAdded: false,
-  },
-  {
-    id: "master",
-    nameKey: "agent.master.name",
-    descKey: "agent.master.desc",
-    avatar: getAvatarUrl("大师.png"),
-    image: getAvatarUrl("Diviner.png"),
-    tagKeys: ["agent.master.tag.1", "agent.master.tag.2", "agent.master.tag.3"],
-    taskKeys: [
-      { titleKey: "agent.master.task.1.title", descKey: "agent.master.task.1.desc" },
-      { titleKey: "agent.master.task.2.title", descKey: "agent.master.task.2.desc" },
-      { titleKey: "agent.master.task.3.title", descKey: "agent.master.task.3.desc" },
-    ],
-    isAdded: false,
-  },
-  {
-    id: "growth-hacker",
-    nameKey: "agent.growthHacker.name",
-    descKey: "agent.growthHacker.desc",
-    avatar: getAvatarUrl("增长黑客.png"),
-    image: getAvatarUrl("Scientist.png"),
-    tagKeys: ["agent.growthHacker.tag.1", "agent.growthHacker.tag.2", "agent.growthHacker.tag.3"],
-    taskKeys: [
-      { titleKey: "agent.growthHacker.task.1.title", descKey: "agent.growthHacker.task.1.desc" },
-      { titleKey: "agent.growthHacker.task.2.title", descKey: "agent.growthHacker.task.2.desc" },
-      { titleKey: "agent.growthHacker.task.3.title", descKey: "agent.growthHacker.task.3.desc" },
-    ],
-    isAdded: false,
-  },
-  {
-    id: "leopard",
-    nameKey: "agent.leopard.name",
-    descKey: "agent.leopard.desc",
-    avatar: getAvatarUrl("金钱豹.png"),
-    image: getAvatarUrl("stock.png"),
-    tagKeys: ["agent.leopard.tag.1", "agent.leopard.tag.2", "agent.leopard.tag.3"],
-    taskKeys: [
-      { titleKey: "agent.leopard.task.1.title", descKey: "agent.leopard.task.1.desc" },
-      { titleKey: "agent.leopard.task.2.title", descKey: "agent.leopard.task.2.desc" },
-      { titleKey: "agent.leopard.task.3.title", descKey: "agent.leopard.task.3.desc" },
-    ],
-    isAdded: false,
-  },
-  {
-    id: "singer",
-    nameKey: "agent.singer.name",
-    descKey: "agent.singer.desc",
-    avatar: getAvatarUrl("Singer.png"),
-    image: getAvatarUrl("Singer.png"),
-    tagKeys: ["agent.singer.tag.1", "agent.singer.tag.2", "agent.singer.tag.3"],
-    taskKeys: [
-      { titleKey: "agent.singer.task.1.title", descKey: "agent.singer.task.1.desc" },
-      { titleKey: "agent.singer.task.2.title", descKey: "agent.singer.task.2.desc" },
-      { titleKey: "agent.singer.task.3.title", descKey: "agent.singer.task.3.desc" },
-    ],
-    isAdded: false,
-  },
-];
+function normalizeRuntimeAgents(value: unknown): RuntimeAgent[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((candidate) => {
+    if (
+      typeof candidate !== "object" ||
+      candidate === null ||
+      typeof (candidate as { id?: unknown }).id !== "string"
+    ) {
+      return [];
+    }
+    const id = (candidate as { id: string }).id;
+    const nameValue = (candidate as { name?: unknown }).name;
+    const descriptionValue = (candidate as { description?: unknown }).description;
+    return [
+      {
+        id,
+        name: typeof nameValue === "string" && nameValue ? nameValue : id,
+        ...(typeof descriptionValue === "string"
+          ? { description: descriptionValue }
+          : {}),
+      },
+    ];
+  });
+}
 
 export const useAgentStore = defineStore("agents", () => {
-  const agentIsAdded = ref<Record<string, boolean>>(
-    Object.fromEntries(AGENT_DEFS.map((d) => [d.id, d.isAdded])),
-  );
-
-  const remoteAgents = ref<Agent[]>([]);
+  const remoteAgents = ref<RuntimeAgent[]>([{ id: "main", name: "Assistant" }]);
+  const currentAgentId = ref("main");
+  const pendingAgentAdds = new Set<string>();
+  const installedAgentIds = computed(() => new Set(remoteAgents.value.map((agent) => agent.id)));
 
-  /** Reactively translated agent list — re-evaluates when locale changes. */
   const agents = computed<Agent[]>(() => {
-    void locale.value; // explicit dependency on locale for reactivity
-    const localAgents = AGENT_DEFS.map((def) => ({
-      ...resolveAgent(def),
-      isAdded: agentIsAdded.value[def.id] ?? def.isAdded,
-    }));
-    if (remoteAgents.value.length === 0) return localAgents;
-    // The gateway's agents.list only carries id/name, not the rich local
-    // metadata (avatars, tags, quick tasks). Keep the local persona for any
-    // id we know about and only append genuinely custom remote agents.
-    const localIds = new Set(localAgents.map((a) => a.id));
-    const extraRemote = remoteAgents.value.filter((a) => !localIds.has(a.id));
-    return [...localAgents, ...extraRemote];
+    void locale.value;
+    return remoteAgents.value.map((runtimeAgent) => {
+      const catalogAgent = AGENT_CATALOG.find((agent) => agent.id === runtimeAgent.id);
+      if (catalogAgent) {
+        return resolveCatalogAgent(catalogAgent, true);
+      }
+      return {
+        ...runtimeAgent,
+        avatar: getAvatarUrl("normal.png"),
+        image: getAvatarUrl("normal.png"),
+        isAdded: true,
+      };
+    });
   });
-  const currentAgentId = ref("main");
-
-  const addedAgents = computed(() => agents.value.filter((a) => a.isAdded));
 
-  const marketAgents = computed(() => agents.value.filter((a) => a.id !== "main"));
-
-  function toggleAgent(agentId: string) {
-    if (agentId in agentIsAdded.value) {
-      agentIsAdded.value[agentId] = !agentIsAdded.value[agentId];
-    }
-  }
+  const marketAgents = computed(() => {
+    void locale.value;
+    return AGENT_CATALOG.filter((agent) => agent.id !== "main").map((agent) =>
+      resolveCatalogAgent(agent, installedAgentIds.value.has(agent.id)),
+    );
+  });
 
   function selectAgent(agentId: string) {
     currentAgentId.value = agentId;
   }
 
+  async function addAgent(agentId: string) {
+    if (installedAgentIds.value.has(agentId) || pendingAgentAdds.has(agentId)) return;
+    pendingAgentAdds.add(agentId);
+    try {
+      const result = await window.openclaw.agents.add(agentId);
+      if (!Array.isArray(result.agents)) {
+        throw new Error("OpenClaw returned an invalid agent roster");
+      }
+      remoteAgents.value = normalizeRuntimeAgents(result.agents);
+    } finally {
+      pendingAgentAdds.delete(agentId);
+    }
+  }
+
   async function fetchAgents() {
     try {
       const result = await window.openclaw.agents.list();
-      if (result.agents && result.agents.length > 0) {
-        remoteAgents.value = result.agents as Agent[];
+      if (Array.isArray(result.agents)) {
+        remoteAgents.value = normalizeRuntimeAgents(result.agents);
       }
-    } catch {
-      // Gateway may not support agents.list yet — keep defaults
+    } catch (error) {
+      console.warn("[agents] Failed to refresh gateway agents:", error);
     }
   }
 
   return {
     agents,
     currentAgentId,
-    addedAgents,
     marketAgents,
-    toggleAgent,
     selectAgent,
+    addAgent,
     fetchAgents,
   };
 });
diff --git a/desktop/renderer/src/views/AgentMarketView.vue b/desktop/renderer/src/views/AgentMarketView.vue
index e936f11..c6825bf 100644
--- a/desktop/renderer/src/views/AgentMarketView.vue
+++ b/desktop/renderer/src/views/AgentMarketView.vue
@@ -9,7 +9,7 @@
         v-for="agent in filteredAgents"
         :key="agent.id"
         :agent="agent"
-        @toggle="agentStore.toggleAgent"
+        @add="handleAdd"
       />
     </div>
   </div>
@@ -17,6 +17,7 @@
 
 <script setup lang="ts">
 import { computed } from "vue";
+import { ElMessage } from "element-plus";
 import { useAgentStore } from "@/stores/agents";
 import { useAgentList } from "@/composables/useAgentList";
 import AgentCard from "@/components/agent/AgentCard.vue";
@@ -24,6 +25,14 @@ import { t } from "@/i18n";
 
 const agentStore = useAgentStore();
 const { filteredAgents } = useAgentList(computed(() => agentStore.marketAgents));
+
+async function handleAdd(agentId: string) {
+  try {
+    await agentStore.addAgent(agentId);
+  } catch {
+    ElMessage.error(t("agentMarket.addFailed"));
+  }
+}
 </script>
 
 <style scoped>
diff --git a/desktop/src/agent-catalog.ts b/desktop/src/agent-catalog.ts
new file mode 100644
index 0000000..a47fe72
--- /dev/null
+++ b/desktop/src/agent-catalog.ts
@@ -0,0 +1,168 @@
+export interface AgentCatalogEntry {
+  id: string;
+  name: string;
+  nameKey: string;
+  descKey: string;
+  avatar: string;
+  image: string;
+  tagKeys: string[];
+  taskKeys: Array<{ titleKey: string; descKey: string }>;
+  installedByDefault: boolean;
+  workspaceDirName?: string;
+  personaProfile?: "master-archive";
+}
+
+export const AGENT_CATALOG: readonly AgentCatalogEntry[] = [
+  {
+    id: "main",
+    name: "Assistant",
+    nameKey: "store.defaultAgent",
+    descKey: "store.defaultAgentDesc",
+    avatar: "normal.png",
+    image: "normal.png",
+    tagKeys: [],
+    taskKeys: [
+      { titleKey: "agent.main.task.1.title", descKey: "agent.main.task.1.desc" },
+      { titleKey: "agent.main.task.2.title", descKey: "agent.main.task.2.desc" },
+      { titleKey: "agent.main.task.3.title", descKey: "agent.main.task.3.desc" },
+    ],
+    installedByDefault: true,
+  },
+  {
+    id: "master-archive",
+    name: "Master Archive",
+    nameKey: "agent.masterArchive.name",
+    descKey: "agent.masterArchive.desc",
+    avatar: "Archaeologist.png",
+    image: "Archaeologist.png",
+    tagKeys: [
+      "agent.masterArchive.tag.1",
+      "agent.masterArchive.tag.2",
+      "agent.masterArchive.tag.3",
+    ],
+    taskKeys: [
+      {
+        titleKey: "agent.masterArchive.task.1.title",
+        descKey: "agent.masterArchive.task.1.desc",
+      },
+      {
+        titleKey: "agent.masterArchive.task.2.title",
+        descKey: "agent.masterArchive.task.2.desc",
+      },
+      {
+        titleKey: "agent.masterArchive.task.3.title",
+        descKey: "agent.masterArchive.task.3.desc",
+      },
+    ],
+    installedByDefault: false,
+    workspaceDirName: "workspace-master-archive",
+    personaProfile: "master-archive",
+  },
+  {
+    id: "coder",
+    name: "Coder",
+    nameKey: "agent.coder.name",
+    descKey: "agent.coder.desc",
+    avatar: "程序猿.png",
+    image: "Coder.png",
+    tagKeys: ["agent.coder.tag.1", "agent.coder.tag.2", "agent.coder.tag.3"],
+    taskKeys: [
+      { titleKey: "agent.coder.task.1.title", descKey: "agent.coder.task.1.desc" },
+      { titleKey: "agent.coder.task.2.title", descKey: "agent.coder.task.2.desc" },
+      { titleKey: "agent.coder.task.3.title", descKey: "agent.coder.task.3.desc" },
+    ],
+    installedByDefault: false,
+  },
+  {
+    id: "painter",
+    name: "Painter",
+    nameKey: "agent.painter.name",
+    descKey: "agent.painter.desc",
+    avatar: "梵高.png",
+    image: "Painter.png",
+    tagKeys: ["agent.painter.tag.1", "agent.painter.tag.2", "agent.painter.tag.3"],
+    taskKeys: [
+      { titleKey: "agent.painter.task.1.title", descKey: "agent.painter.task.1.desc" },
+      { titleKey: "agent.painter.task.2.title", descKey: "agent.painter.task.2.desc" },
+      { titleKey: "agent.painter.task.3.title", descKey: "agent.painter.task.3.desc" },
+    ],
+    installedByDefault: false,
+  },
+  {
+    id: "master",
+    name: "Master",
+    nameKey: "agent.master.name",
+    descKey: "agent.master.desc",
+    avatar: "大师.png",
+    image: "Diviner.png",
+    tagKeys: ["agent.master.tag.1", "agent.master.tag.2", "agent.master.tag.3"],
+    taskKeys: [
+      { titleKey: "agent.master.task.1.title", descKey: "agent.master.task.1.desc" },
+      { titleKey: "agent.master.task.2.title", descKey: "agent.master.task.2.desc" },
+      { titleKey: "agent.master.task.3.title", descKey: "agent.master.task.3.desc" },
+    ],
+    installedByDefault: false,
+  },
+  {
+    id: "growth-hacker",
+    name: "Growth Hacker",
+    nameKey: "agent.growthHacker.name",
+    descKey: "agent.growthHacker.desc",
+    avatar: "增长黑客.png",
+    image: "Scientist.png",
+    tagKeys: [
+      "agent.growthHacker.tag.1",
+      "agent.growthHacker.tag.2",
+      "agent.growthHacker.tag.3",
+    ],
+    taskKeys: [
+      {
+        titleKey: "agent.growthHacker.task.1.title",
+        descKey: "agent.growthHacker.task.1.desc",
+      },
+      {
+        titleKey: "agent.growthHacker.task.2.title",
+        descKey: "agent.growthHacker.task.2.desc",
+      },
+      {
+        titleKey: "agent.growthHacker.task.3.title",
+        descKey: "agent.growthHacker.task.3.desc",
+      },
+    ],
+    installedByDefault: false,
+  },
+  {
+    id: "leopard",
+    name: "Leopard",
+    nameKey: "agent.leopard.name",
+    descKey: "agent.leopard.desc",
+    avatar: "金钱豹.png",
+    image: "stock.png",
+    tagKeys: ["agent.leopard.tag.1", "agent.leopard.tag.2", "agent.leopard.tag.3"],
+    taskKeys: [
+      { titleKey: "agent.leopard.task.1.title", descKey: "agent.leopard.task.1.desc" },
+      { titleKey: "agent.leopard.task.2.title", descKey: "agent.leopard.task.2.desc" },
+      { titleKey: "agent.leopard.task.3.title", descKey: "agent.leopard.task.3.desc" },
+    ],
+    installedByDefault: false,
+  },
+  {
+    id: "singer",
+    name: "Singer",
+    nameKey: "agent.singer.name",
+    descKey: "agent.singer.desc",
+    avatar: "Singer.png",
+    image: "Singer.png",
+    tagKeys: ["agent.singer.tag.1", "agent.singer.tag.2", "agent.singer.tag.3"],
+    taskKeys: [
+      { titleKey: "agent.singer.task.1.title", descKey: "agent.singer.task.1.desc" },
+      { titleKey: "agent.singer.task.2.title", descKey: "agent.singer.task.2.desc" },
+      { titleKey: "agent.singer.task.3.title", descKey: "agent.singer.task.3.desc" },
+    ],
+    installedByDefault: false,
+  },
+];
+
+export const DEFAULT_AGENT_IDS = AGENT_CATALOG.filter(
+  (agent) => agent.installedByDefault,
+).map((agent) => agent.id);
diff --git a/desktop/src/agent-personas.test.ts b/desktop/src/agent-personas.test.ts
new file mode 100644
index 0000000..928ada3
--- /dev/null
+++ b/desktop/src/agent-personas.test.ts
@@ -0,0 +1,214 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  AGENT_PERSONAS,
+  DEFAULT_AGENT_PERSONAS,
+  ensureAgentPersonasConfig,
+  getAgentPersona,
+  getAgentWorkspacePath,
+  listConfiguredAgents,
+  resolveAgentPersonaWorkspace,
+  seedAgentPersonaWorkspaces,
+} from "./agent-personas";
+
+const tempDirs: string[] = [];
+
+function createStateDir(): string {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "microclaw-agent-personas-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("agent personas", () => {
+  it("registers only main for a new installation", () => {
+    const stateDir = createStateDir();
+    const config = { agents: { defaults: { model: "custom/model" } } };
+
+    expect(ensureAgentPersonasConfig(config, stateDir).changed).toBe(true);
+    expect(listConfiguredAgents(config)).toEqual([
+      { id: "main", name: "Assistant" },
+    ]);
+    expect(ensureAgentPersonasConfig(config, stateDir).changed).toBe(false);
+  });
+
+  it("migrates unsupported entries data back to the runtime list", () => {
+    const stateDir = createStateDir();
+    const agents: Record<string, unknown> = {
+      entries: {
+        main: { name: "Existing Assistant", default: true },
+      },
+    };
+    const config = {
+      agents,
+    };
+
+    expect(ensureAgentPersonasConfig(config, stateDir).changed).toBe(true);
+    expect(agents).not.toHaveProperty("entries");
+    expect(listConfiguredAgents(config)).toEqual([
+      { id: "main", name: "Existing Assistant" },
+    ]);
+  });
+
+  it("preserves the effective legacy default and removes extra default markers", () => {
+    const stateDir = createStateDir();
+    const config = {
+      agents: {
+        list: [
+          { id: "Coder", name: "Coder", default: true },
+          { id: "MAIN", name: "Assistant", default: true },
+        ],
+      },
+    };
+
+    ensureAgentPersonasConfig(config, stateDir);
+
+    expect(config.agents.list.find((entry) => entry.id === "coder")).toMatchObject({
+      default: true,
+    });
+    expect(config.agents.list.find((entry) => entry.id === "main")).not.toHaveProperty(
+      "default",
+    );
+  });
+
+  it("rejects normalized id collisions without rewriting the legacy roster", () => {
+    const stateDir = createStateDir();
+    const list = [
+      { id: "Code Geek", name: "First" },
+      { id: "code-geek", name: "Second" },
+    ];
+    const config = { agents: { list } };
+
+    expect(() => ensureAgentPersonasConfig(config, stateDir)).toThrow(
+      'both normalize to "code-geek"',
+    );
+    expect(config.agents).toEqual({ list });
+  });
+
+  it("merges preview-only entries without overriding the runtime list", () => {
+    const stateDir = createStateDir();
+    const config = {
+      agents: {
+        list: [{ id: "main", name: "Runtime Assistant", default: true }],
+        entries: {
+          main: { name: "Preview Assistant", workspace: "preview-main" },
+          analyst: { name: "Analyst", workspace: "preview-analyst" },
+        },
+      },
+    };
+
+    ensureAgentPersonasConfig(config, stateDir);
+
+    expect(config.agents).not.toHaveProperty("entries");
+    expect(config.agents.list.find((entry) => entry.id === "main")).toMatchObject({
+      name: "Runtime Assistant",
+      workspace: "preview-main",
+      default: true,
+    });
+    expect(config.agents.list.find((entry) => entry.id === "analyst")).toMatchObject({
+      name: "Analyst",
+      workspace: "preview-analyst",
+    });
+  });
+
+  it("seeds the Master Archive workspace with its operating context", () => {
+    const stateDir = createStateDir();
+    const config = { agents: {} };
+    const persona = getAgentPersona("master-archive");
+    if (!persona) throw new Error("Master Archive persona is not registered");
+    ensureAgentPersonasConfig(config, stateDir, [
+      ...DEFAULT_AGENT_PERSONAS,
+      persona,
+    ]);
+    expect(listConfiguredAgents(config).map((agent) => agent.id)).toEqual([
+      "main",
+      "master-archive",
+    ]);
+    const created = seedAgentPersonaWorkspaces(config, stateDir, "## Shared safety rule");
+    const workspace = getAgentWorkspacePath(stateDir, persona);
+    if (!workspace) throw new Error("Master Archive workspace is not configured");
+
+    expect(workspace).toBe(path.join(stateDir, "workspace-master-archive"));
+    expect(created).toHaveLength(3);
+    expect(fs.readFileSync(path.join(workspace, "SOUL.md"), "utf-8")).toContain(
+      "## Shared safety rule",
+    );
+    expect(fs.readFileSync(path.join(workspace, "AGENTS.md"), "utf-8")).toContain(
+      "Never move or rename files before the user approves",
+    );
+    expect(fs.readFileSync(path.join(workspace, "IDENTITY.md"), "utf-8")).toContain(
+      "Name: Master Archive",
+    );
+  });
+
+  it("does not seed a Popular Agent before it is installed", () => {
+    const stateDir = createStateDir();
+    const config = { agents: {} };
+    ensureAgentPersonasConfig(config, stateDir);
+
+    expect(seedAgentPersonaWorkspaces(config, stateDir)).toEqual([]);
+    expect(fs.existsSync(path.join(stateDir, "workspace-master-archive"))).toBe(
+      false,
+    );
+  });
+
+  it("does not overwrite user-customized workspace files", () => {
+    const stateDir = createStateDir();
+    const customWorkspace = path.join(stateDir, "custom-archive");
+    const config = {
+      agents: {
+        list: [
+          { id: "main", default: true },
+          { id: "master-archive", workspace: customWorkspace },
+        ],
+      },
+    };
+    ensureAgentPersonasConfig(config, stateDir);
+    seedAgentPersonaWorkspaces(config, stateDir);
+    const soulPath = path.join(customWorkspace, "SOUL.md");
+    fs.writeFileSync(soulPath, "custom persona\n", "utf-8");
+
+    const updated = seedAgentPersonaWorkspaces(config, stateDir, "## Required appendix");
+
+    expect(updated).toEqual([soulPath]);
+    expect(fs.readFileSync(soulPath, "utf-8")).toBe(
+      "custom persona\n\n## Required appendix\n",
+    );
+    expect(
+      resolveAgentPersonaWorkspace(config, stateDir, AGENT_PERSONAS[1], {}, stateDir, stateDir),
+    ).toBe(customWorkspace);
+  });
+
+  it("matches OpenClaw home and gateway cwd path resolution", () => {
+    const stateDir = createStateDir();
+    const gatewayCwd = path.join(stateDir, "gateway");
+    const openClawHome = path.join(stateDir, "openclaw-home");
+    const config = {
+      agents: {
+        list: [
+          { id: "main", default: true },
+          { id: "master-archive", workspace: "~/archive" },
+        ],
+      },
+    };
+    ensureAgentPersonasConfig(config, stateDir);
+
+    expect(
+      resolveAgentPersonaWorkspace(
+        config,
+        stateDir,
+        AGENT_PERSONAS[1],
+        { OPENCLAW_HOME: openClawHome },
+        path.join(stateDir, "os-home"),
+        gatewayCwd,
+      ),
+    ).toBe(path.join(openClawHome, "archive"));
+  });
+});
diff --git a/desktop/src/agent-personas.ts b/desktop/src/agent-personas.ts
new file mode 100644
index 0000000..fd56851
--- /dev/null
+++ b/desktop/src/agent-personas.ts
@@ -0,0 +1,436 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { AGENT_CATALOG, DEFAULT_AGENT_IDS } from "./agent-catalog";
+
+interface WorkspaceFiles {
+  "AGENTS.md": string;
+  "IDENTITY.md": string;
+  "SOUL.md": string;
+}
+
+export interface AgentPersona {
+  id: string;
+  name: string;
+  workspaceDirName?: string;
+  workspaceFiles?: WorkspaceFiles;
+}
+
+export interface AgentRosterConfig {
+  agents?: Record<string, unknown>;
+}
+
+export interface AgentPersonasConfigResult {
+  changed: boolean;
+}
+
+const MASTER_ARCHIVE_SOUL_MD = `# SOUL.md - Master Archive
+
+You are Master Archive, a meticulous digital archivist for local files and documents.
+
+## Character
+
+- Organized, privacy-conscious, calm, and efficient.
+- Prefer clear inventories, previews, and verifiable results over clever shortcuts.
+- Keep responses concise and structure large results as plans, tables, or checklists.
+
+## Safety
+
+- Treat every local file as private.
+- Inspect and explain the scope before moving, renaming, deleting, overwriting, or bulk-editing files.
+- Require explicit confirmation before destructive or difficult-to-reverse actions.
+- Preserve source files during conversion unless the user explicitly asks otherwise.
+- Respect the exact path requested by the user. Report blocked access instead of silently using another location.
+
+## Results
+
+- State what changed, where outputs were written, and what was left untouched.
+- Report partial failures explicitly, including the affected file and reason.
+- Never describe an operation as complete until its outputs have been checked.
+`;
+
+const MASTER_ARCHIVE_AGENTS_MD = `# AGENTS.md - Master Archive Operating Guide
+
+## Mission
+
+Bring order to local digital assets through safe batch conversion, preview-first organization, and evidence-based document extraction.
+
+## Standard workflow
+
+1. Confirm the target paths, desired output, naming rules, and exclusions.
+2. Inventory the relevant files using read-only inspection.
+3. Present a concise plan when the operation moves, renames, deletes, overwrites, or reorganizes data.
+4. Execute only the requested or approved changes.
+5. Verify outputs and summarize successes, skips, and failures.
+
+## Batch conversion
+
+- Detect unsupported or encrypted inputs before starting.
+- Define output naming and collision behavior up front.
+- Preserve originals by default.
+- For merge operations, show the input order and verify the merged output opens successfully.
+
+## File and directory cleanup
+
+- Never move or rename files before the user approves the preview plan.
+- Base categories on the user's rules; use file type, project, and date only as sensible defaults.
+- Avoid deleting duplicates automatically. Present duplicate candidates with evidence for review.
+- Produce a before-and-after summary with file counts.
+
+## Document summarization and extraction
+
+- Distinguish source facts from inference.
+- Cite the source filename and page, section, or timestamp when available.
+- Preserve dates, owners, amounts, and deadlines exactly as written.
+- Consolidate action items into a checklist with owner, due date, source, and status fields when present.
+
+## Tools
+
+- Prefer the installed document, spreadsheet, PDF, and media skills over ad hoc converters.
+- Batch compatible reads and conversions, but isolate failures so one bad file does not hide other results.
+`;
+
+const MASTER_ARCHIVE_IDENTITY_MD = `# IDENTITY.md
+
+- Name: Master Archive
+- Role: Local digital archivist
+- Vibe: Meticulous, private, and dependable
+`;
+
+type PersonaProfile = NonNullable<
+  (typeof AGENT_CATALOG)[number]["personaProfile"]
+>;
+
+const PERSONA_PROFILES: Record<PersonaProfile, WorkspaceFiles> = {
+  "master-archive": {
+    "AGENTS.md": MASTER_ARCHIVE_AGENTS_MD,
+    "IDENTITY.md": MASTER_ARCHIVE_IDENTITY_MD,
+    "SOUL.md": MASTER_ARCHIVE_SOUL_MD,
+  },
+};
+
+export const AGENT_PERSONAS: readonly AgentPersona[] = AGENT_CATALOG.map((agent) => ({
+  id: agent.id,
+  name: agent.name,
+  workspaceDirName: agent.workspaceDirName,
+  workspaceFiles: agent.personaProfile ? PERSONA_PROFILES[agent.personaProfile] : undefined,
+}));
+
+export const DEFAULT_AGENT_PERSONAS = AGENT_PERSONAS.filter((persona) =>
+  DEFAULT_AGENT_IDS.includes(persona.id),
+);
+
+export function getAgentPersona(agentId: string): AgentPersona | undefined {
+  return AGENT_PERSONAS.find((persona) => persona.id === agentId);
+}
+
+export function getAgentWorkspacePath(
+  stateDir: string,
+  persona: AgentPersona,
+): string | undefined {
+  return persona.workspaceDirName ? path.join(stateDir, persona.workspaceDirName) : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function normalizeAgentId(value: string): string {
+  const normalized = value.trim().toLowerCase();
+  return (
+    normalized
+      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/^-+/, "")
+      .replace(/-+$/, "")
+      .slice(0, 64) || "main"
+  );
+}
+
+function createAgentEntry(persona: AgentPersona, stateDir: string): Record<string, unknown> {
+  const entry: Record<string, unknown> = { name: persona.name };
+  const workspace = getAgentWorkspacePath(stateDir, persona);
+  if (workspace) entry.workspace = workspace;
+  return entry;
+}
+
+export function ensureAgentPersonasConfig(
+  config: AgentRosterConfig,
+  stateDir: string,
+  personas: readonly AgentPersona[] = DEFAULT_AGENT_PERSONAS,
+): AgentPersonasConfigResult {
+  if (config.agents !== undefined && !isRecord(config.agents)) {
+    throw new Error("Invalid agents configuration");
+  }
+
+  const agents = config.agents ?? {};
+  const sourceEntries: Array<{
+    id: string;
+    config: Record<string, unknown>;
+    source: "list" | "entries";
+  }> = [];
+  const hasList = Object.hasOwn(agents, "list") && agents.list !== undefined;
+
+  if (hasList) {
+    if (!Array.isArray(agents.list)) {
+      throw new Error("Invalid agents.list configuration");
+    }
+    for (const entry of agents.list) {
+      if (!isRecord(entry) || typeof entry.id !== "string" || !entry.id.trim()) {
+        throw new Error("Invalid agent entry in agents.list");
+      }
+      const { id, ...entryConfig } = entry;
+      sourceEntries.push({ id, config: entryConfig, source: "list" });
+    }
+  }
+  if (Object.hasOwn(agents, "entries") && agents.entries !== undefined) {
+    if (!isRecord(agents.entries)) {
+      throw new Error("Invalid agents.entries configuration");
+    }
+    for (const [id, entry] of Object.entries(agents.entries)) {
+      if (!id.trim() || !isRecord(entry)) {
+        throw new Error(`Invalid agent entry "${id}" in agents.entries`);
+      }
+      sourceEntries.push({ id, config: { ...entry }, source: "entries" });
+    }
+  }
+
+  const entries: Array<{ id: string } & Record<string, unknown>> = [];
+  const normalizedIds = new Map<
+    string,
+    { rawId: string; source: "list" | "entries"; entry: { id: string } & Record<string, unknown> }
+  >();
+  for (const source of sourceEntries) {
+    const normalizedId = normalizeAgentId(source.id);
+    const previous = normalizedIds.get(normalizedId);
+    if (previous !== undefined) {
+      const bothCanonical =
+        previous.rawId.trim().toLowerCase() === normalizedId &&
+        source.id.trim().toLowerCase() === normalizedId;
+      if (previous.source !== source.source && bothCanonical) {
+        if (previous.source === "list") {
+          for (const [key, value] of Object.entries(source.config)) {
+            if (key !== "id" && !Object.hasOwn(previous.entry, key)) {
+              previous.entry[key] = value;
+            }
+          }
+        } else {
+          Object.assign(previous.entry, source.config, { id: normalizedId });
+          previous.source = "list";
+        }
+        continue;
+      }
+      throw new Error(
+        `Agent ids "${previous.rawId}" and "${source.id}" both normalize to "${normalizedId}"`,
+      );
+    }
+    const entry = { id: normalizedId };
+    Object.assign(entry, source.config, { id: normalizedId });
+    normalizedIds.set(normalizedId, {
+      rawId: source.id,
+      source: source.source,
+      entry,
+    });
+    entries.push(entry);
+  }
+
+  const sourceDefault =
+    sourceEntries.find((entry) => entry.config.default === true) ?? sourceEntries[0];
+  const defaultAgentId = sourceDefault ? normalizeAgentId(sourceDefault.id) : "main";
+
+  for (const persona of personas) {
+    if (normalizedIds.has(persona.id)) continue;
+    const entry = { id: persona.id, ...createAgentEntry(persona, stateDir) };
+    entries.push(entry);
+    normalizedIds.set(persona.id, { rawId: persona.id, source: "list", entry });
+  }
+
+  for (const entry of entries) {
+    if (entry.id === defaultAgentId) {
+      entry.default = true;
+    } else if (entry.default === true) {
+      delete entry.default;
+    }
+  }
+
+  const changed =
+    !hasList ||
+    Object.hasOwn(agents, "entries") ||
+    JSON.stringify(agents.list) !== JSON.stringify(entries);
+  agents.list = entries;
+  delete agents.entries;
+  config.agents = agents;
+  return { changed };
+}
+
+export function listConfiguredAgents(
+  config: AgentRosterConfig,
+): Array<{ id: string; name: string }> {
+  if (!isRecord(config.agents) || !Array.isArray(config.agents.list)) return [];
+  return config.agents.list.flatMap((candidate) => {
+    if (!isRecord(candidate) || typeof candidate.id !== "string") return [];
+    const id = normalizeAgentId(candidate.id);
+    return [
+      {
+        id,
+        name:
+          typeof candidate.name === "string" && candidate.name.trim()
+            ? candidate.name
+            : id,
+      },
+    ];
+  });
+}
+
+function normalizeHomeValue(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return !trimmed || trimmed === "undefined" || trimmed === "null" ? undefined : trimmed;
+}
+
+function resolveEffectiveHome(
+  env: NodeJS.ProcessEnv,
+  homeDir: string,
+  cwd: string,
+): string {
+  const osHome =
+    normalizeHomeValue(env.HOME) ??
+    normalizeHomeValue(env.USERPROFILE) ??
+    normalizeHomeValue(homeDir);
+  const configuredHome = normalizeHomeValue(env.OPENCLAW_HOME);
+  const rawHome = configuredHome
+    ? configuredHome.replace(/^~(?=$|[\\/])/, osHome ?? "")
+    : osHome;
+  return path.resolve(cwd, rawHome ?? ".");
+}
+
+function resolveUserPath(
+  value: string,
+  env: NodeJS.ProcessEnv,
+  homeDir: string,
+  cwd: string,
+): string {
+  const trimmed = value.trim();
+  if (trimmed.startsWith("~")) {
+    const expanded = trimmed.replace(
+      /^~(?=$|[\\/])/,
+      resolveEffectiveHome(env, homeDir, cwd),
+    );
+    return path.resolve(cwd, expanded);
+  }
+  return path.resolve(cwd, trimmed);
+}
+
+export function resolveAgentPersonaWorkspace(
+  config: AgentRosterConfig,
+  stateDir: string,
+  persona: AgentPersona,
+  env: NodeJS.ProcessEnv = process.env,
+  homeDir = os.homedir(),
+  cwd = process.cwd(),
+): string {
+  const agents = isRecord(config.agents) ? config.agents : {};
+  const entries = Array.isArray(agents.list)
+    ? agents.list.filter((entry): entry is Record<string, unknown> => isRecord(entry))
+    : [];
+  const entry =
+    entries.find(
+      (candidate) =>
+        typeof candidate.id === "string" && normalizeAgentId(candidate.id) === persona.id,
+    ) ?? {};
+  if (typeof entry.workspace === "string" && entry.workspace.trim()) {
+    return resolveUserPath(entry.workspace, env, homeDir, cwd);
+  }
+
+  const defaults = isRecord(agents.defaults) ? agents.defaults : {};
+  const defaultWorkspace =
+    typeof defaults.workspace === "string" && defaults.workspace.trim()
+      ? resolveUserPath(defaults.workspace, env, homeDir, cwd)
+      : undefined;
+  const defaultAgentId =
+    normalizeAgentId(
+      String(entries.find((candidate) => candidate.default === true)?.id ?? entries[0]?.id ?? "main"),
+    );
+
+  if (persona.id === defaultAgentId) {
+    return defaultWorkspace ?? path.join(stateDir, "workspace");
+  }
+  return defaultWorkspace
+    ? path.join(defaultWorkspace, persona.id)
+    : path.join(stateDir, `workspace-${persona.id}`);
+}
+
+export function seedAgentPersonaWorkspaces(
+  config: AgentRosterConfig,
+  stateDir: string,
+  soulAppendix = "",
+  env: NodeJS.ProcessEnv = process.env,
+  homeDir = os.homedir(),
+  cwd = process.cwd(),
+): string[] {
+  const updatedFiles: string[] = [];
+  const configuredIds = new Set(listConfiguredAgents(config).map((agent) => agent.id));
+
+  for (const persona of AGENT_PERSONAS) {
+    if (!persona.workspaceFiles || !configuredIds.has(persona.id)) continue;
+    updatedFiles.push(
+      ...seedAgentPersonaWorkspace(
+        config,
+        stateDir,
+        persona,
+        soulAppendix,
+        env,
+        homeDir,
+        cwd,
+      ),
+    );
+  }
+
+  return updatedFiles;
+}
+
+export function seedAgentPersonaWorkspace(
+  config: AgentRosterConfig,
+  stateDir: string,
+  persona: AgentPersona,
+  soulAppendix = "",
+  env: NodeJS.ProcessEnv = process.env,
+  homeDir = os.homedir(),
+  cwd = process.cwd(),
+): string[] {
+  if (!persona.workspaceFiles) return [];
+  const updatedFiles: string[] = [];
+  const workspaceDir = resolveAgentPersonaWorkspace(
+    config,
+    stateDir,
+    persona,
+    env,
+    homeDir,
+    cwd,
+  );
+
+  fs.mkdirSync(workspaceDir, { recursive: true });
+  for (const [filename, source] of Object.entries(persona.workspaceFiles)) {
+    const filePath = path.join(workspaceDir, filename);
+    if (fs.existsSync(filePath)) {
+      if (filename === "SOUL.md" && soulAppendix) {
+        const existing = fs.readFileSync(filePath, "utf-8");
+        const appendixMarker =
+          soulAppendix.split(/\r?\n/).find((line) => line.startsWith("## ")) ??
+          soulAppendix.trim();
+        if (appendixMarker && !existing.includes(appendixMarker)) {
+          fs.appendFileSync(filePath, `\n${soulAppendix.trim()}\n`, "utf-8");
+          updatedFiles.push(filePath);
+        }
+      }
+      continue;
+    }
+
+    const content =
+      filename === "SOUL.md" && soulAppendix
+        ? `${source.trimEnd()}\n\n${soulAppendix.trim()}\n`
+        : `${source.trimEnd()}\n`;
+    fs.writeFileSync(filePath, content, "utf-8");
+    updatedFiles.push(filePath);
+  }
+
+  return updatedFiles;
+}
diff --git a/desktop/src/gateway-lifecycle.test.ts b/desktop/src/gateway-lifecycle.test.ts
index 2e962d7..eda72bc 100644
--- a/desktop/src/gateway-lifecycle.test.ts
+++ b/desktop/src/gateway-lifecycle.test.ts
@@ -1,5 +1,19 @@
 import { describe, expect, it, vi } from "vitest";
-import { hardRestartGateway } from "./gateway-lifecycle";
+import { hardRestartGateway, requiresExternalGatewayStop } from "./gateway-lifecycle";
+
+describe("requiresExternalGatewayStop", () => {
+  it("protects an unowned listener when the roster must be reloaded", () => {
+    expect(requiresExternalGatewayStop(true, true, false, false)).toBe(true);
+  });
+
+  it("allows a managed Gateway to restart for a roster change", () => {
+    expect(requiresExternalGatewayStop(true, true, true, true)).toBe(false);
+  });
+
+  it("allows an unchanged external Gateway to be reused", () => {
+    expect(requiresExternalGatewayStop(true, false, false, false)).toBe(false);
+  });
+});
 
 describe("hardRestartGateway", () => {
   it("stops the client and process, waits for the port, then starts", async () => {
diff --git a/desktop/src/gateway-lifecycle.ts b/desktop/src/gateway-lifecycle.ts
index 78b8d82..52f155f 100644
--- a/desktop/src/gateway-lifecycle.ts
+++ b/desktop/src/gateway-lifecycle.ts
@@ -8,6 +8,15 @@ export type GatewayRestartDependencies = {
   pollMs: number;
 };
 
+export function requiresExternalGatewayStop(
+  alreadyRunning: boolean,
+  rosterChanged: boolean,
+  spawnedByUs: boolean,
+  hasManagedProcess: boolean,
+): boolean {
+  return alreadyRunning && rosterChanged && !(spawnedByUs && hasManagedProcess);
+}
+
 export async function hardRestartGateway(dependencies: GatewayRestartDependencies): Promise<void> {
   if (dependencies.pollMs <= 0) {
     throw new Error("gateway restart poll interval must be positive");
diff --git a/desktop/src/main.ts b/desktop/src/main.ts
index 5131abe..afa4bde 100644
--- a/desktop/src/main.ts
+++ b/desktop/src/main.ts
@@ -3,9 +3,10 @@ import * as path from "path";
 import * as fs from "fs";
 import * as http from "http";
 import * as net from "net";
+import * as os from "os";
 import { ChildProcess, execFileSync, spawn } from "child_process";
 import { GatewayClient, type ChatEventPayload } from "./gateway-client";
-import { hardRestartGateway } from "./gateway-lifecycle";
+import { hardRestartGateway, requiresExternalGatewayStop } from "./gateway-lifecycle";
 import { createTray, destroyTray } from "./tray";
 import Store from "electron-store";
 import {
@@ -25,6 +26,7 @@ import {
 } from "./openclaw-upgrade-recovery";
 import {
   getOpenClawStateDir,
+  loadGatewayEnvironment,
   loadStateDirEnv,
   resolveBuiltinSkillsDir,
   resolveNodePath,
@@ -76,6 +78,17 @@ import {
   ensureGitHubCopilotProviderPlugin,
   ensureSelectedModelProviderPlugins,
 } from "./model-provider-plugins";
+import {
+  DEFAULT_AGENT_PERSONAS,
+  ensureAgentPersonasConfig,
+  getAgentPersona,
+  listConfiguredAgents,
+  resolveAgentPersonaWorkspace,
+  seedAgentPersonaWorkspace,
+  seedAgentPersonaWorkspaces,
+  type AgentPersona,
+  type AgentRosterConfig,
+} from "./agent-personas";
 
 /**
  * Normalize a directory path for comparison/storage.
@@ -203,6 +216,7 @@ let gatewayRestartPromise: Promise<void> | null = null;
 let pendingSyncPermissionRequests = 0;
 /** True when we spawned the gateway ourselves (vs. connecting to an existing one). */
 let gatewaySpawnedByUs = false;
+let agentAdditionInProgress = false;
 /** Tracks whether the post-spawn channel kick has already fired. */
 let postSpawnRestartDone = false;
 /** Tool execution sandbox (runs AI agent commands inside AppContainer). */
@@ -1209,68 +1223,215 @@ function ensurePluginsAllow(): void {
 }
 
 /**
- * Agent personas the MicroClaw UI can start a chat with. OpenClaw only accepts
- * an agent id that appears in `agents.list`; when that list is empty it knows
- * only the built-in "main" agent and rejects every other id with
- * `unknown agent id "<id>"`. Keep these ids in sync with the renderer's
- * AGENT_DEFS (desktop/renderer/src/stores/agents.ts) so every selectable
- * persona can actually be chatted with.
+ * Ensure the default MicroClaw persona exists in the OpenClaw roster.
+ * OpenClaw 2026.7.1-1 uses `agents.list`; unsupported `agents.entries` data
+ * written by preview builds is migrated back before personas are added. Existing
+ * entries are preserved by id and the config is only rewritten when something
+ * changes. Both processes consume the shared agent catalog.
  */
-const AGENT_PERSONAS: readonly { id: string; name: string }[] = [
-  { id: "main", name: "Assistant" },
-  { id: "coder", name: "Coder" },
-  { id: "painter", name: "Painter" },
-  { id: "master", name: "Master" },
-  { id: "growth-hacker", name: "Growth Hacker" },
-  { id: "leopard", name: "Leopard" },
-  { id: "singer", name: "Singer" },
-];
+function prepareAgentPersonas(
+  stateDir: string,
+): { config: AgentRosterConfig; changed: boolean } | null {
+  const config = readConfig();
+  if (!config) return null;
+  const result = ensureAgentPersonasConfig(config, stateDir);
+  return { config, changed: result.changed };
+}
 
-/**
- * Register every UI agent persona in `agents.list` so OpenClaw accepts a chat
- * request for it. Entries inherit the model from `agents.defaults`; "main" is
- * marked as the default agent so behavior is unchanged for it. Existing entries
- * are preserved by id (never overwritten), and the config is only rewritten
- * when something actually changed.
- */
-function ensureAgentsList(): void {
+function persistAgentPersonas(config: AgentRosterConfig): void {
+  writeConfigTextAtomically(JSON.stringify(config, null, 2));
+  console.log(
+    `[config] Registered agent personas: ${listConfiguredAgents(config)
+      .map((agent) => agent.id)
+      .join(", ")}`,
+  );
+}
+
+function writeConfigTextAtomically(contents: string): void {
+  const configPath = getConfigPath();
+  const temporaryPath = `${configPath}.microclaw-${process.pid}-${Date.now()}.tmp`;
+  fs.writeFileSync(temporaryPath, contents, "utf-8");
   try {
-    const config = readConfig();
-    if (!config) return;
-    if (!config.agents) config.agents = {};
-    const existing = Array.isArray(config.agents.list) ? config.agents.list : [];
-    const knownIds = new Set(
-      existing
-        .map((entry: { id?: unknown }) => (typeof entry?.id === "string" ? entry.id : ""))
-        .filter(Boolean)
+    fs.renameSync(temporaryPath, configPath);
+  } finally {
+    if (fs.existsSync(temporaryPath)) fs.unlinkSync(temporaryPath);
+  }
+}
+
+function failForExternalGateway(port: number): never {
+  const message =
+    `Agent configuration changed, but Gateway port ${port} is owned by another process. ` +
+    "Stop that Gateway and retry so MicroClaw can apply the new roster safely.";
+  gatewayStatus = "failed";
+  mainWindow?.webContents.send("gateway:status", "failed");
+  mainWindow?.webContents.send("gateway:log", `[error] ${message}`);
+  throw new Error(message);
+}
+
+function seedSpecialistAgentWorkspaces(
+  config: AgentRosterConfig,
+  stateDir: string,
+  entryPath: string,
+  gatewayEnvironment: Record<string, string>,
+): void {
+  try {
+    const seededFiles = seedAgentPersonaWorkspaces(
+      config,
+      stateDir,
+      DECLARE_ACCESS_SECTION,
+      gatewayEnvironment,
+      os.homedir(),
+      path.dirname(entryPath),
     );
+    if (seededFiles.length > 0) {
+      console.log(`[seed] Created specialist agent workspace files: ${seededFiles.join(", ")}`);
+    }
+  } catch (err) {
+    console.warn("[seed] Failed to create specialist agent workspace files:", err);
+  }
+}
 
-    const list = [...existing];
-    let changed = false;
-    for (const persona of AGENT_PERSONAS) {
-      if (knownIds.has(persona.id)) continue;
-      const entry: Record<string, unknown> = { id: persona.id, name: persona.name };
-      if (persona.id === "main") entry.default = true;
-      list.push(entry);
-      changed = true;
+interface WorkspaceSnapshot {
+  directory: string;
+  directoryExisted: boolean;
+  files: Array<{ path: string; contents: string | null }>;
+}
+
+function captureAgentWorkspace(
+  config: AgentRosterConfig,
+  stateDir: string,
+  persona: AgentPersona,
+  gatewayEnvironment: Record<string, string>,
+  entryPath: string,
+): WorkspaceSnapshot | null {
+  if (!persona.workspaceFiles) return null;
+  const directory = resolveAgentPersonaWorkspace(
+    config,
+    stateDir,
+    persona,
+    gatewayEnvironment,
+    os.homedir(),
+    path.dirname(entryPath),
+  );
+  return {
+    directory,
+    directoryExisted: fs.existsSync(directory),
+    files: Object.keys(persona.workspaceFiles).map((filename) => {
+      const filePath = path.join(directory, filename);
+      return {
+        path: filePath,
+        contents: fs.existsSync(filePath) ? fs.readFileSync(filePath, "utf-8") : null,
+      };
+    }),
+  };
+}
+
+function restoreAgentWorkspace(snapshot: WorkspaceSnapshot | null): void {
+  if (!snapshot) return;
+  for (const file of snapshot.files) {
+    if (file.contents === null) {
+      if (fs.existsSync(file.path)) fs.unlinkSync(file.path);
+    } else {
+      fs.writeFileSync(file.path, file.contents, "utf-8");
     }
+  }
+  if (
+    !snapshot.directoryExisted &&
+    fs.existsSync(snapshot.directory) &&
+    fs.readdirSync(snapshot.directory).length === 0
+  ) {
+    fs.rmdirSync(snapshot.directory);
+  }
+}
 
-    // Once the list is non-empty, exactly one entry must be the default agent.
-    if (list.length > 0 && !list.some((entry: { default?: unknown }) => entry?.default)) {
-      const main = list.find((entry: { id?: unknown }) => entry?.id === "main");
-      if (main) {
-        (main as Record<string, unknown>).default = true;
-        changed = true;
+async function addCatalogAgent(
+  agentId: string,
+): Promise<{ agents: Array<{ id: string; name: string }> }> {
+  const persona = getAgentPersona(agentId);
+  if (!persona || DEFAULT_AGENT_PERSONAS.some((candidate) => candidate.id === agentId)) {
+    throw new Error(`Unknown installable agent template "${agentId}"`);
+  }
+
+  const stateDir = getOpenClawStateDir();
+  const configPath = getConfigPath();
+  const originalConfigText = fs.readFileSync(configPath, "utf-8");
+  const config = readConfig();
+  if (!config) throw new Error("OpenClaw configuration is unavailable");
+
+  const result = ensureAgentPersonasConfig(config, stateDir, [
+    ...DEFAULT_AGENT_PERSONAS,
+    persona,
+  ]);
+  if (!result.changed) {
+    return { agents: listConfiguredAgents(config) };
+  }
+
+  const alreadyRunning = await checkExistingGateway(gatewayPort);
+  const managedGateway = gatewaySpawnedByUs && gatewayProcess !== null;
+  if (
+    requiresExternalGatewayStop(
+      alreadyRunning,
+      true,
+      gatewaySpawnedByUs,
+      gatewayProcess !== null,
+    )
+  ) {
+    throw new Error(
+      "Cannot add an agent while MicroClaw is connected to an externally managed Gateway",
+    );
+  }
+
+  const entryPath = resolveOpenClawEntry();
+  const gatewayEnvironment = loadGatewayEnvironment(stateDir);
+  const workspaceSnapshot = captureAgentWorkspace(
+    config,
+    stateDir,
+    persona,
+    gatewayEnvironment,
+    entryPath,
+  );
+  let restartAttempted = false;
+
+  try {
+    persistAgentPersonas(config);
+    seedAgentPersonaWorkspace(
+      config,
+      stateDir,
+      persona,
+      DECLARE_ACCESS_SECTION,
+      gatewayEnvironment,
+      os.homedir(),
+      path.dirname(entryPath),
+    );
+    restartAttempted = true;
+    await restartManagedGateway(`Adding agent ${agentId}`);
+    return { agents: listConfiguredAgents(config) };
+  } catch (error) {
+    const rollbackErrors: unknown[] = [];
+    try {
+      writeConfigTextAtomically(originalConfigText);
+    } catch (rollbackError) {
+      rollbackErrors.push(rollbackError);
+    }
+    try {
+      restoreAgentWorkspace(workspaceSnapshot);
+    } catch (rollbackError) {
+      rollbackErrors.push(rollbackError);
+    }
+    if (restartAttempted && managedGateway) {
+      try {
+        await restartManagedGateway(`Rolling back failed agent addition ${agentId}`);
+      } catch (rollbackError) {
+        rollbackErrors.push(rollbackError);
       }
     }
-
-    if (changed) {
-      config.agents.list = list;
-      fs.writeFileSync(getConfigPath(), JSON.stringify(config, null, 2), "utf-8");
-      console.log(`[config] Registered agent personas in agents.list: ${list.map((e: { id?: unknown }) => e?.id).join(", ")}`);
+    if (rollbackErrors.length > 0) {
+      throw new AggregateError(
+        [error, ...rollbackErrors],
+        `Failed to add agent "${agentId}" and fully restore the previous state`,
+      );
     }
-  } catch (err) {
-    console.error("[config] Failed to update agents.list:", err);
+    throw error;
   }
 }
 
@@ -1697,20 +1858,44 @@ async function startGatewayInner(): Promise<void> {
   gatewayToken = config?.gateway?.auth?.token || "";
   const configuredPort = config?.gateway?.port || DEFAULT_PORT;
   gatewayPort = configuredPort;
+  const stateDir = getOpenClawStateDir();
+  const nodePath = resolveNodePath();
+  const entryPath = resolveOpenClawEntry();
+  const gatewayEnvironment = loadGatewayEnvironment(stateDir);
 
   // Ensure plugins.allow includes enabled plugins so they load synchronously
   // (avoids the race where auto-discovered plugins miss the channel-start sweep)
   ensurePluginsAllow();
 
-  // Register the UI agent personas so OpenClaw will accept a chat request for
-  // any of them (otherwise only the built-in "main" agent is recognized).
-  ensureAgentsList();
+  const preparedPersonas = prepareAgentPersonas(stateDir);
+  const agentRosterChanged = preparedPersonas?.changed ?? false;
 
   // If gateway is already healthy, just connect WS and return — no new process.
   // Callers that need replacement use restartManagedGateway(), which stops the
   // old process and waits for the port before invoking this function.
   const alreadyRunning = await checkExistingGateway(configuredPort);
-  if (alreadyRunning) {
+  if (
+    requiresExternalGatewayStop(
+      alreadyRunning,
+      agentRosterChanged,
+      gatewaySpawnedByUs,
+      gatewayProcess !== null,
+    )
+  ) {
+    failForExternalGateway(configuredPort);
+  }
+  if (preparedPersonas?.changed) {
+    persistAgentPersonas(preparedPersonas.config);
+  }
+  if (preparedPersonas) {
+    seedSpecialistAgentWorkspaces(
+      preparedPersonas.config,
+      stateDir,
+      entryPath,
+      gatewayEnvironment,
+    );
+  }
+  if (alreadyRunning && !agentRosterChanged) {
     console.log(`[gateway] Already healthy on port ${configuredPort} — skipping spawn`);
     gatewaySpawnedByUs = false;
     gatewayStatus = "running";
@@ -1719,10 +1904,10 @@ async function startGatewayInner(): Promise<void> {
     startHealthMonitor();
     return;
   }
-
-  const stateDir = getOpenClawStateDir();
-  const nodePath = resolveNodePath();
-  const entryPath = resolveOpenClawEntry();
+  if (alreadyRunning) {
+    console.log("[gateway] Agent roster changed — restarting to load canonical configuration");
+    gwClient?.stop();
+  }
 
   // Kill any old gateway on this port
   stopGatewayProcess();
@@ -1786,8 +1971,7 @@ async function startGatewayInner(): Promise<void> {
   // to the renderer via the gateway:log IPC channel (visible in Settings).
 
   const gwEnv: Record<string, string> = {
-    ...(process.env as Record<string, string>),
-    ...loadStateDirEnv(),
+    ...gatewayEnvironment,
     OPENCLAW_STATE_DIR: stateDir,
     NODE_OPTIONS: "--disable-warning=ExperimentalWarning --dns-result-order=ipv4first",
     NODE_ENV: "production",
@@ -2993,12 +3177,22 @@ function registerIpcHandlers(): void {
 
   // --- Agents ---
   ipcMain.handle("agents:list", async () => {
-    if (!gwClient?.connected) return { agents: [] };
+    if (!gwClient?.connected) throw new Error("Gateway not connected");
+    return await gwClient.listAgents();
+  });
+  ipcMain.handle("agents:add", async (_event, agentId: string) => {
+    if (typeof agentId !== "string" || !agentId.trim()) {
+      throw new Error("Agent id is required");
+    }
+    if (!gwClient?.connected) throw new Error("Gateway not connected");
+    if (agentAdditionInProgress) {
+      throw new Error("Another agent is already being added");
+    }
+    agentAdditionInProgress = true;
     try {
-      return await gwClient.listAgents();
-    } catch (err) {
-      console.warn("[agents:list] failed:", err);
-      return { agents: [] };
+      return await addCatalogAgent(agentId);
+    } finally {
+      agentAdditionInProgress = false;
     }
   });
 
diff --git a/desktop/src/path-resolver.test.ts b/desktop/src/path-resolver.test.ts
index d3d7a72..fa66472 100644
--- a/desktop/src/path-resolver.test.ts
+++ b/desktop/src/path-resolver.test.ts
@@ -28,6 +28,7 @@ vi.mock("fs", async () => {
 import * as path from "path";
 import {
   getOpenClawStateDir,
+  loadGatewayEnvironment,
   loadStateDirEnv,
   resolveNodePath,
   resolveOpenClawEntry,
@@ -116,6 +117,25 @@ describe("loadStateDirEnv", () => {
   });
 });
 
+describe("loadGatewayEnvironment", () => {
+  it("uses state-directory values over the desktop process environment", () => {
+    mockReadFileSync.mockReturnValue(
+      "OPENCLAW_HOME=D:\\state-home\nSTATE_ONLY=from-state\n",
+    );
+
+    expect(
+      loadGatewayEnvironment("D:\\state", {
+        OPENCLAW_HOME: "C:\\process-home",
+        PROCESS_ONLY: "from-process",
+      }),
+    ).toMatchObject({
+      OPENCLAW_HOME: "D:\\state-home",
+      PROCESS_ONLY: "from-process",
+      STATE_ONLY: "from-state",
+    });
+  });
+});
+
 // ── resolveNodePath ─────────────────────────────────────────────────
 
 describe("resolveNodePath", () => {
diff --git a/desktop/src/path-resolver.ts b/desktop/src/path-resolver.ts
index c8b257f..aa33213 100644
--- a/desktop/src/path-resolver.ts
+++ b/desktop/src/path-resolver.ts
@@ -53,6 +53,17 @@ export function loadStateDirEnv(stateDir?: string): Record<string, string> {
   return result;
 }
 
+export function loadGatewayEnvironment(
+  stateDir: string,
+  baseEnvironment: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const environment: Record<string, string> = {};
+  for (const [key, value] of Object.entries(baseEnvironment)) {
+    if (value !== undefined) environment[key] = value;
+  }
+  return { ...environment, ...loadStateDirEnv(stateDir) };
+}
+
 /**
  * Resolve the path to `node.exe`.
  *
diff --git a/desktop/src/preload.ts b/desktop/src/preload.ts
index 62a0dcc..c4b0895 100644
--- a/desktop/src/preload.ts
+++ b/desktop/src/preload.ts
@@ -151,6 +151,7 @@ contextBridge.exposeInMainWorld("openclaw", {
   // --- Agents ---
   agents: {
     list: () => ipcRenderer.invoke("agents:list"),
+    add: (agentId: string) => ipcRenderer.invoke("agents:add", agentId),
   },
 
   // --- Channels ---
diff --git a/docs/hero-scenarios.md b/docs/hero-scenarios.md
new file mode 100644
index 0000000..34cbdcb
--- /dev/null
+++ b/docs/hero-scenarios.md
@@ -0,0 +1,186 @@
+# MicroClaw Hero Scenarios
+
+## MVP agent matrix
+
+| Specialist agent | Persona and professional role | Hero scenarios |
+| --- | --- | --- |
+| **Master Archive (归藏大师)** | Meticulous digital archivist organizing local folders, converting files, and summarizing bulk documents | Batch file conversion and processing; smart file and directory cleanup; bulk document summarization and extraction |
+| **Creative Muse (灵感创客)** | Witty creative content strategist crafting Rednote posts, video scripts, and multi-platform text | Rednote viral seed posts; short-video storyboards and scripts; multi-platform content adaptation |
+| **Intel Analyst (前哨智囊)** | Vigilant intelligence analyst delivering personal morning briefs, social trends, and deep research | Personal morning briefings; industry and social trend monitoring; deep research and synthesis |
+| **Dr. Pulse (系统神医)** | Attentive PC doctor diagnosing system issues, clearing storage, and tuning OS settings | System inspection and guided repair; natural-language system tuning; scenario-based work and play preparation |
+| **Code Geek (灵码极客)** | Sharp engineer building apps and features, auditing code, generating tests, and fixing failures | Feature and web app prototyping; code and vulnerability review; build and stack-trace diagnostics |
+
+## Master Archive (归藏大师)
+
+### Persona and professional role
+
+- **Persona and tone:** Meticulous, organized, privacy-conscious, and efficient. Operates as a trusted digital archivist who brings order and structure to local digital assets.
+- **Domain expertise:** Local file taxonomy, directory restructuring, multi-format document and media conversion (PDF, Word, Excel, audio, and video), and bulk document summarization.
+- **Main responsibilities:** Safely organize cluttered local directories, execute batch file transformations, and digest bulk documents into structured summaries on user command.
+
+### Scenario 1: Batch file format conversion and processing
+
+Transforms local documents, images, audio, or video in batches according to user-defined rules, including format conversion, file merging, and media stream extraction.
+
+Example commands:
+
+- "Convert all .docx project proposals in this folder to PDF and merge them into a single file."
+- "Extract the audio from all .mp4 meeting recordings in /Recordings and save them as .mp3 files."
+
+### Scenario 2: Smart file and directory cleanup
+
+Scans a specified local folder, categorizes files by project, type, or date, presents an interactive preview plan, and performs the proposed sorting only after user confirmation.
+
+Example commands:
+
+- "Organize my messy project folder - show me the plan first." The agent scans the files, proposes categories such as `01_Docs`, `02_Assets`, and `03_Finals`, and moves files after approval.
+- "Organize my local photo library into subfolders by year and month, keeping RAW files separate from JPEGs."
+
+### Scenario 3: Bulk document summarization and information extraction
+
+Reads one or more local documents, such as PDF reports, Word plans, and meeting notes, then extracts key takeaways, data tables, deadlines, or action items.
+
+Example commands:
+
+- "Read this 50-page industry PDF report and generate a 1-page summary with key trends, data figures, and conclusions."
+- "Scan through my meeting transcript files from this week and consolidate all mentioned deadlines and action items into a clean checklist."
+
+## Creative Muse (灵感创客)
+
+### Persona and professional role
+
+- **Persona and tone:** Creative, trend-aware, audience-oriented, and witty, with a strong understanding of Chinese social platform conventions.
+- **Domain expertise:** Rednote (小红书) seed posts, short-video and live-stream scripts, and multi-platform copy adaptation.
+- **Main responsibilities:** Convert raw ideas, product highlights, or master copy into platform-specific content packages ready for publishing.
+
+### Scenario 1: Rednote viral seed post creation
+
+Generates engaging, emoji-rich Rednote copy, title candidates, and structured post outlines from product features, lifestyle experiences, or local store visits.
+
+Example commands:
+
+- "I visited a new zen-style tea house today. Write 5 catchy Rednote titles with emojis, a 300-word review post highlighting key tea drinks, and 5 trending hashtags."
+- "Write a Rednote post for a rose moisturizing cream targeting young professionals, highlighting ingredient safety and texture."
+
+### Scenario 2: Short-video storyboarding and scriptwriting
+
+Transforms concepts or product features into structured short-video or live-stream scripts with visual directions, audio cues, timecodes, and dialogue.
+
+Example commands:
+
+- "Turn this wireless earbud feature sheet into a 60-second Douyin video script with visual camera directions, sound effects, and spoken dialogue."
+- "Draft an outline for a 5-minute Bilibili tech review video covering smart home gadgets, including a strong 3-second opening hook."
+
+### Scenario 3: Multi-platform content repurposing and adaptation
+
+Rewrites master copy into versions tailored to the style, length, and audience expectations of specific platforms.
+
+Example commands:
+
+- "Take my 1500-word WeChat Official Account article and adapt it into three versions: a Bilibili dynamic post, a Feishu document summary, and a Rednote card note."
+- "Polish this product launch text into three different tones: casual and friendly, geeky and professional, and humorous."
+
+## Intel Analyst (前哨智囊)
+
+### Persona and professional role
+
+- **Persona and tone:** Vigilant, objective, concise, and analytical. Functions as an on-demand personal intelligence analyst and strategic advisor.
+- **Domain expertise:** Personal morning context synthesis, Chinese technology and social-media trend analysis, and structured deep research.
+- **Main responsibilities:** Search, aggregate, analyze, and synthesize online and personal information into structured intelligence digests and research reports.
+
+### Scenario 1: Personal morning briefing and executive digest
+
+Aggregates weather, commute traffic, the user's meeting schedule, and urgent unread email into a concise one-page digest.
+
+Example commands:
+
+- "Generate my morning briefing: today's Beijing weather, commute traffic updates, my meeting schedule, and urgent emails that need a response."
+- "Summarize my personal schedule for today, listing my key meetings, deadlines, and reminders."
+
+### Scenario 2: Industry and social-media trend monitoring
+
+Searches and analyzes Chinese technology media such as 36Kr, ITHome, and Huxiu, plus platforms such as Weibo and Zhihu, for requested topics and developments.
+
+Example commands:
+
+- "Summarize top tech news from 36Kr and ITHome over the past 24 hours regarding AI Agents, providing a 1-sentence takeaway for each."
+- "Gather current trending discussions on Weibo and Zhihu regarding 'Smart Home Devices' and summarize the main public opinions."
+
+### Scenario 3: Deep research and topic synthesis
+
+Conducts multi-source web research on a topic, product comparison, or travel request and synthesizes findings into a structured brief or comparison table.
+
+Example commands:
+
+- "Research the top 3 popular ergonomic office chairs, compare their key selling points, user pros/cons from reviews, and price ranges into a comparison table."
+- "Find recommended 3-day travel routes in Hangzhou focusing on cafes and walkable neighborhoods, and compile a structured itinerary with highlights and tips."
+
+## Dr. Pulse (系统神医)
+
+### Persona and professional role
+
+- **Persona and tone:** Calm, authoritative, cautious, and transparent. Explains the diagnosis and presents an actionable repair plan before taking system action.
+- **Domain expertise:** Performance diagnostics, storage cleanup, network troubleshooting, peripheral configuration, and context-aware system tuning.
+- **Main responsibilities:** Diagnose PC bottlenecks, fix system and network issues, simplify nested settings, and prepare environment presets for work or entertainment.
+
+### Scenario 1: System health inspection, diagnosis, and guided repair
+
+Inspects performance, connectivity, or disk pressure, identifies the likely root cause, and presents a repair plan before requesting confirmation to execute changes.
+
+Example commands:
+
+- "My PC can't load web pages or connect to Feishu - run a diagnostic first." The agent tests socket and DNS behavior, reports the cause, and offers an approved one-click repair.
+- "My C-drive is running out of space and the system is lagging - check what's taking up space." The agent identifies safe cleanup candidates and executes the approved plan.
+
+### Scenario 2: Natural-language system tuning and peripheral setup
+
+Translates natural-language requests into precise system-setting or peripheral configuration changes.
+
+Example commands:
+
+- "Increase screen text size by 15%, turn on Night Light, and mute notification sounds."
+- "Connect to the shared office HP printer on the local network and print a test page."
+
+### Scenario 3: Scenario-based work and play environment preparation
+
+Configures system parameters, notifications, app launches, and window layouts for activities such as focused work, video calls, or gaming.
+
+Example commands:
+
+- "Prepare my PC for deep work mode." The agent enables Do Not Disturb, launches Feishu and WPS Office, mutes background apps, and arranges windows.
+- "Get my PC ready for a video conference." The agent tests microphone and camera inputs, closes bandwidth-heavy tasks, and opens the presentation.
+
+## Code Geek (灵码极客)
+
+### Persona and professional role
+
+- **Persona and tone:** Passionate, sharp, pragmatic, and resourceful. Works alongside the developer as an expert engineer.
+- **Domain expertise:** Feature and web app prototyping, boilerplate generation, automated code review, vulnerability detection, unit-test generation, and terminal diagnostics.
+- **Main responsibilities:** Build software from natural-language requirements, inspect code for defects and vulnerabilities, and diagnose build or runtime failures.
+
+### Scenario 1: Feature and web app prototyping
+
+Generates software features, standalone utilities, web pages, or project scaffolding from high-level requirements.
+
+Example commands:
+
+- "Build a dark-mode, minimalist portfolio web page using single-file HTML and Tailwind CSS."
+- "Write a Python CLI script that extracts top tech news from a web page and formats them into a clean Markdown table."
+
+### Scenario 2: Code review, bug, and vulnerability audit
+
+Analyzes local diffs, modules, or pull requests for security vulnerabilities, logic errors, performance bottlenecks, and style violations.
+
+Example commands:
+
+- "Review my staged git diff in /src/auth for security vulnerabilities, memory leaks, or unhandled exceptions before I commit."
+- "Audit this Python data processing script for memory overhead and performance bottlenecks, and suggest optimizations."
+
+### Scenario 3: Terminal build and stack-trace diagnostics
+
+Parses compiler errors, build logs, and runtime stack traces, identifies the failing line and root cause, and proposes or applies a verified fix.
+
+Example commands:
+
+- "My npm run build failed with a TypeScript type mismatch error - analyze this error log and fix the code."
+- "Explain why this Python script threw a RecursionError in the stack trace and update the code to fix it."