squad-openclaw 2026.2.2017 → 2026.2.2019

package/README.md

@@ -15,18 +15,48 @@ OpenClaw gateway plugin for [Squad](https://squad.ceo) — provides entity regis
 
 ## State Directory Resolution
 
-All paths in this plugin (and throughout this README) that reference `~/.openclaw` resolve via the `OPENCLAW_STATE_DIR` environment variable when set. This supports Docker and other containerized deployments where the OpenClaw data directory may not be at the default location.
+All paths in this plugin (and throughout this README) that reference `~/.openclaw` resolve via environment override when set. This supports Docker and other containerized deployments where the OpenClaw data directory may not be at the default location.
+
+Resolution priority:
+
+1. `OPENCLAW_STATE_DIR` (canonical)
+2. `OPENCLAW_DIR` (compat alias)
+3. `os.homedir() + "/.openclaw"` (default)
 
 | Environment | Typical path | How it's resolved |
 |---|---|---|
 | Standard install | `~/.openclaw` | Default — `os.homedir() + "/.openclaw"` |
-| Docker | `/root/data/.openclaw` | `OPENCLAW_STATE_DIR=/root/data/.openclaw` |
+| Docker | `/data/.openclaw` | `OPENCLAW_STATE_DIR=/data/.openclaw` (or `OPENCLAW_DIR=/data/.openclaw`) |
 | Custom / NAS | `/mnt/data/.openclaw` | `OPENCLAW_STATE_DIR=/mnt/data/.openclaw` |
 
 **This variable only controls where the plugin looks for OpenClaw's own data directory.** It does not grant the plugin access to the parent directory or any other part of the filesystem. All security restrictions (blocked directories, allowed roots, write protection) are enforced relative to the resolved state directory — not the filesystem root.
 
 The resolution logic lives in a single shared module ([`src/paths.ts`](src/paths.ts)) imported by every file that needs the state directory path.
 
+### Docker Workspace Mapping
+
+If your container mounts the real workspace outside the OpenClaw state directory (for example, `/data/workspace`), create a symlink so OpenClaw-compatible tools can still resolve `.../.openclaw/workspace`:
+
+```bash
+mkdir -p /data/.openclaw /data/workspace
+ln -sfn /data/workspace /data/.openclaw/workspace
+```
+
+Then start your gateway/server with explicit env vars (useful when `.env` is not loaded):
+
+```bash
+PORT=3334 \
+OPENCLAW_STATE_DIR=/data/.openclaw \
+OPENCLAW_DIR=/data/.openclaw \
+node server.js
+```
+
+Quick verification:
+
+```bash
+ls -ld /data/.openclaw /data/.openclaw/workspace /data/workspace /data/.openclaw/openclaw.json
+```
+
 ## Security Model
 
 This plugin enforces a **defense-in-depth** security model with four independent layers. All security rules are hard-coded and non-configurable (except `allowedRoots`) so they can be verified by reading the source code. The bundle is intentionally **not minified** to allow security auditing of the distributed code.
@@ -231,7 +261,7 @@ Configure in your gateway's `openclaw.json` under the plugin section:
 
 | Key | Type | Default | Description |
 |---|---|---|---|
-| `fs.allowedRoots` | `string[]` | `["~/.openclaw"]` | Restrict filesystem operations to these directories. Hardcoded blocks on `credentials/`, `devices/`, `identity/`, `relay/squad-relay.json`, and `.bak` files always apply regardless. |
+| `fs.allowedRoots` | `string[]` | `[resolved OpenClaw state dir]` | Restrict filesystem operations to these directories. Hardcoded blocks on `credentials/`, `devices/`, `identity/`, `relay/squad-relay.json`, and `.bak` files always apply regardless. |
 
 ## Source Code
 

package/dist/index.js

@@ -105,7 +105,7 @@ function registerAgentMethods(api) {
 // src/entities.ts
 import { Type as T } from "@sinclair/typebox";
 import path4 from "path";
-import fs3 from "fs";
+import fs4 from "fs";
 
 // src/watcher.ts
 import path from "path";
@@ -360,14 +360,31 @@ function startWatcher(configDir, onFsChange) {
 }
 
 // src/filesystem.ts
-import fs2 from "fs";
+import fs3 from "fs";
 import path3 from "path";
 
 // src/paths.ts
 import path2 from "path";
 import os from "os";
+import fs2 from "fs";
 function getOpenclawStateDir() {
-  return process.env.OPENCLAW_STATE_DIR || path2.join(os.homedir(), ".openclaw");
+  if (process.env.OPENCLAW_STATE_DIR) {
+    return process.env.OPENCLAW_STATE_DIR;
+  }
+  if (process.env.OPENCLAW_CONFIG_PATH) {
+    return path2.dirname(process.env.OPENCLAW_CONFIG_PATH);
+  }
+  const legacyDir = process.env.OPENCLAW_DIR;
+  if (legacyDir) {
+    const resolvedLegacyDir = path2.resolve(legacyDir);
+    const configPath = path2.join(resolvedLegacyDir, "openclaw.json");
+    const hasStateMarkers = fs2.existsSync(configPath) || fs2.existsSync(path2.join(resolvedLegacyDir, "agents")) || fs2.existsSync(path2.join(resolvedLegacyDir, "workspace"));
+    const looksLikeStateDir = resolvedLegacyDir.endsWith(`${path2.sep}.openclaw`);
+    if (hasStateMarkers || looksLikeStateDir) {
+      return resolvedLegacyDir;
+    }
+  }
+  return path2.join(os.homedir(), ".openclaw");
 }
 
 // src/filesystem.ts
@@ -491,7 +508,7 @@ function err(message) {
   };
 }
 function listDir(dirPath, opts) {
-  const dirents = fs2.readdirSync(dirPath, { withFileTypes: true });
+  const dirents = fs3.readdirSync(dirPath, { withFileTypes: true });
   const results = [];
   for (const dirent of dirents) {
     if (!opts.includeHidden && dirent.name.startsWith(".")) continue;
@@ -502,7 +519,7 @@ function listDir(dirPath, opts) {
     else if (dirent.isSymbolicLink()) type = "symlink";
     const entry = { name: dirent.name, path: entryPath, type };
     try {
-      const stat = fs2.statSync(entryPath);
+      const stat = fs3.statSync(entryPath);
       entry.size = stat.size;
       entry.modified = stat.mtime.toISOString();
     } catch {
@@ -526,7 +543,7 @@ function filterSensitiveEntries(entries) {
   });
 }
 function registerFilesystemTools(api) {
-  const DEFAULT_ALLOWED_ROOTS = ["~/.openclaw"];
+  const DEFAULT_ALLOWED_ROOTS = [OPENCLAW_DIR];
   const allowedRoots = api.pluginConfig?.["fs.allowedRoots"] ?? DEFAULT_ALLOWED_ROOTS;
   api.registerTool({
     name: "fs_read",
@@ -551,8 +568,8 @@ function registerFilesystemTools(api) {
       try {
         const filePath = validateAndBlockSensitive(params.path, allowedRoots);
         const encoding = params.encoding ?? "utf-8";
-        let content = fs2.readFileSync(filePath, encoding);
-        const stat = fs2.statSync(filePath);
+        let content = fs3.readFileSync(filePath, encoding);
+        const stat = fs3.statSync(filePath);
         if (isOpenclawJson(filePath) && encoding === "utf-8") {
           content = redactOpenclawJson(content);
         }
@@ -602,10 +619,10 @@ function registerFilesystemTools(api) {
         const encoding = params.encoding ?? "utf-8";
         const mkdir = params.mkdir !== false;
         if (mkdir) {
-          fs2.mkdirSync(path3.dirname(filePath), { recursive: true });
+          fs3.mkdirSync(path3.dirname(filePath), { recursive: true });
         }
-        fs2.writeFileSync(filePath, content, encoding);
-        const stat = fs2.statSync(filePath);
+        fs3.writeFileSync(filePath, content, encoding);
+        const stat = fs3.statSync(filePath);
         return ok({
           path: filePath,
           size: stat.size,
@@ -674,7 +691,7 @@ function registerFilesystemTools(api) {
     async execute(_id, params) {
       try {
         const targetPath = validateWritePath(params.path, allowedRoots);
-        fs2.mkdirSync(targetPath, { recursive: true });
+        fs3.mkdirSync(targetPath, { recursive: true });
         return ok({
           path: targetPath,
           created: true
@@ -707,7 +724,7 @@ function registerFilesystemTools(api) {
       try {
         const resolvedOld = validateWritePath(params.oldPath, allowedRoots);
         const resolvedNew = validateWritePath(params.newPath, allowedRoots);
-        fs2.renameSync(resolvedOld, resolvedNew);
+        fs3.renameSync(resolvedOld, resolvedNew);
         return ok({
           oldPath: resolvedOld,
           newPath: resolvedNew,
@@ -736,12 +753,12 @@ function registerFilesystemTools(api) {
     async execute(_id, params) {
       try {
         const targetPath = validateWritePath(params.path, allowedRoots);
-        const stat = fs2.statSync(targetPath);
+        const stat = fs3.statSync(targetPath);
         const wasDirectory = stat.isDirectory();
         if (wasDirectory) {
-          fs2.rmSync(targetPath, { recursive: true });
+          fs3.rmSync(targetPath, { recursive: true });
         } else {
-          fs2.unlinkSync(targetPath);
+          fs3.unlinkSync(targetPath);
         }
         return ok({
           path: targetPath,
@@ -793,7 +810,7 @@ function scanAgents(configDir) {
   const now = Date.now();
   let entries;
   try {
-    entries = fs3.readdirSync(configDir, { withFileTypes: true });
+    entries = fs4.readdirSync(configDir, { withFileTypes: true });
   } catch {
     return;
   }
@@ -807,7 +824,7 @@ function scanAgents(configDir) {
     const metadata = { workspacePath };
     const identityPath = path4.join(workspacePath, "IDENTITY.md");
     try {
-      const content = fs3.readFileSync(identityPath, "utf-8");
+      const content = fs4.readFileSync(identityPath, "utf-8");
       const parsed = parseIdentityName(content);
       if (parsed) name = parsed;
     } catch {
@@ -815,7 +832,7 @@ function scanAgents(configDir) {
     if (name === agentId) {
       const agentJsonPath = path4.join(workspacePath, "agent.json");
       try {
-        const raw = fs3.readFileSync(agentJsonPath, "utf-8");
+        const raw = fs4.readFileSync(agentJsonPath, "utf-8");
         const config = JSON.parse(raw);
         if (config.displayName) name = config.displayName;
         if (config.model) metadata.model = config.model;
@@ -844,7 +861,7 @@ function scanSkills(configDir) {
   scanSkillsDir(globalSkillsDir, "global", now);
   let entries;
   try {
-    entries = fs3.readdirSync(configDir, { withFileTypes: true });
+    entries = fs4.readdirSync(configDir, { withFileTypes: true });
   } catch {
     return;
   }
@@ -860,7 +877,7 @@ function scanSkills(configDir) {
 function scanSkillsDir(skillsDir, scope, now) {
   let entries;
   try {
-    entries = fs3.readdirSync(skillsDir, { withFileTypes: true });
+    entries = fs4.readdirSync(skillsDir, { withFileTypes: true });
   } catch {
     return;
   }
@@ -871,7 +888,7 @@ function scanSkillsDir(skillsDir, scope, now) {
     let name = skillKey;
     for (const manifestName of ["manifest.json", "package.json"]) {
       try {
-        const raw = fs3.readFileSync(
+        const raw = fs4.readFileSync(
           path4.join(skillPath, manifestName),
           "utf-8"
         );
@@ -902,7 +919,7 @@ function scanPlugins2(configDir) {
   const extensionsDir = path4.join(configDir, "extensions");
   let entries;
   try {
-    entries = fs3.readdirSync(extensionsDir, { withFileTypes: true });
+    entries = fs4.readdirSync(extensionsDir, { withFileTypes: true });
   } catch {
     return;
   }
@@ -911,7 +928,7 @@ function scanPlugins2(configDir) {
     const pluginDir = path4.join(extensionsDir, dir.name);
     const manifestPath = path4.join(pluginDir, "openclaw.plugin.json");
     try {
-      const raw = fs3.readFileSync(manifestPath, "utf-8");
+      const raw = fs4.readFileSync(manifestPath, "utf-8");
       const manifest = JSON.parse(raw);
       const pluginId = manifest.id || dir.name;
       const name = manifest.name || pluginId;
@@ -934,7 +951,7 @@ function scanPlugins2(configDir) {
 function scanTools(configDir) {
   const now = Date.now();
   try {
-    const raw = fs3.readFileSync(
+    const raw = fs4.readFileSync(
       path4.join(configDir, "openclaw.json"),
       "utf-8"
     );
@@ -997,7 +1014,7 @@ function scanMedia(configDir) {
 function scanMediaDir(dirPath, now) {
   let entries;
   try {
-    entries = fs3.readdirSync(dirPath, { withFileTypes: true });
+    entries = fs4.readdirSync(dirPath, { withFileTypes: true });
   } catch {
     return;
   }
@@ -1024,7 +1041,7 @@ function scanMediaDir(dirPath, now) {
       let size;
       let mtime = now;
       try {
-        const stat = fs3.statSync(entryPath);
+        const stat = fs4.statSync(entryPath);
         size = stat.size;
         mtime = stat.mtimeMs;
       } catch {
@@ -1142,7 +1159,7 @@ function registerEntityTools(api, onFsChange) {
 // src/sql.ts
 import { execFile } from "child_process";
 import path5 from "path";
-import fs4 from "fs";
+import fs5 from "fs";
 import { Type as T2 } from "@sinclair/typebox";
 var HOME_DIR2 = process.env.HOME ?? "/root";
 var ALLOWED_DATA_DIR = path5.join(getOpenclawStateDir(), "squad-ceo-data");
@@ -1158,7 +1175,7 @@ function validateDbPath(dbPath) {
     );
   }
   try {
-    const stat = fs4.statSync(resolved);
+    const stat = fs5.statSync(resolved);
     if (!stat.isFile()) {
       throw new Error(`Not a file: ${dbPath}`);
     }
@@ -1225,7 +1242,7 @@ function registerSqlTools(api) {
 
 // src/version.ts
 import { execSync as execSync2 } from "child_process";
-import fs5 from "fs";
+import fs6 from "fs";
 import path6 from "path";
 import { fileURLToPath } from "url";
 var PACKAGE_NAME = "squad-openclaw";
@@ -1236,7 +1253,7 @@ var VERIFY_INTERVAL_MS = 500;
 var RESTART_BUFFER_MS = 5e3;
 function readInstalledVersionFromConfig() {
   try {
-    const raw = fs5.readFileSync(CONFIG_PATH, "utf-8");
+    const raw = fs6.readFileSync(CONFIG_PATH, "utf-8");
     const cfg = JSON.parse(raw);
     const v = cfg?.plugins?.installs?.[PACKAGE_NAME]?.version;
     return typeof v === "string" ? v : null;
@@ -1247,7 +1264,7 @@ function readInstalledVersionFromConfig() {
 function reconcileInstallMetadata(verification) {
   if (!verification.installPath || !verification.packageVersion) return;
   try {
-    const raw = fs5.readFileSync(CONFIG_PATH, "utf-8");
+    const raw = fs6.readFileSync(CONFIG_PATH, "utf-8");
     const config = JSON.parse(raw);
     if (!config.plugins || typeof config.plugins !== "object") config.plugins = {};
     if (!config.plugins.installs || typeof config.plugins.installs !== "object") {
@@ -1270,7 +1287,7 @@ function reconcileInstallMetadata(verification) {
       ...entry,
       enabled: true
     };
-    fs5.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
+    fs6.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), "utf-8");
   } catch {
   }
 }
@@ -1278,7 +1295,7 @@ function getCurrentVersion() {
   const thisFile = fileURLToPath(import.meta.url);
   const pkgPath = path6.resolve(path6.dirname(thisFile), "..", "package.json");
   try {
-    const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
+    const pkg = JSON.parse(fs6.readFileSync(pkgPath, "utf-8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -1323,7 +1340,7 @@ function compareVersions(a, b) {
 function verifyInstalledPluginState() {
   let configRaw;
   try {
-    configRaw = fs5.readFileSync(CONFIG_PATH, "utf-8");
+    configRaw = fs6.readFileSync(CONFIG_PATH, "utf-8");
   } catch (err2) {
     const msg = err2 instanceof Error ? err2.message : String(err2);
     return {
@@ -1367,7 +1384,7 @@ function verifyInstalledPluginState() {
     path6.join(installPath, "openclaw.plugin.json"),
     path6.join(installPath, "dist", "index.js")
   ];
-  const requiredFilesMissing = requiredFiles.filter((p) => !fs5.existsSync(p));
+  const requiredFilesMissing = requiredFiles.filter((p) => !fs6.existsSync(p));
   if (requiredFilesMissing.length > 0) {
     return {
       ok: false,
@@ -1381,7 +1398,7 @@ function verifyInstalledPluginState() {
   let installedPackage;
   try {
     installedPackage = JSON.parse(
-      fs5.readFileSync(path6.join(installPath, "package.json"), "utf-8")
+      fs6.readFileSync(path6.join(installPath, "package.json"), "utf-8")
     );
   } catch (err2) {
     const msg = err2 instanceof Error ? err2.message : String(err2);
@@ -1396,7 +1413,7 @@ function verifyInstalledPluginState() {
   }
   try {
     JSON.parse(
-      fs5.readFileSync(path6.join(installPath, "openclaw.plugin.json"), "utf-8")
+      fs6.readFileSync(path6.join(installPath, "openclaw.plugin.json"), "utf-8")
     );
   } catch (err2) {
     const msg = err2 instanceof Error ? err2.message : String(err2);
@@ -1486,7 +1503,7 @@ function registerVersionMethods(api) {
         let updateOutput = "";
         let configBackup = null;
         try {
-          configBackup = fs5.readFileSync(CONFIG_PATH, "utf-8");
+          configBackup = fs6.readFileSync(CONFIG_PATH, "utf-8");
         } catch {
         }
         runDoctorFixSilently();
@@ -1505,7 +1522,7 @@ function registerVersionMethods(api) {
           } catch (installErr) {
             if (configBackup) {
               try {
-                fs5.writeFileSync(CONFIG_PATH, configBackup, "utf-8");
+                fs6.writeFileSync(CONFIG_PATH, configBackup, "utf-8");
               } catch {
               }
             }
@@ -1523,7 +1540,7 @@ function registerVersionMethods(api) {
         if (!verification.ok) {
           if (configBackup) {
             try {
-              fs5.writeFileSync(CONFIG_PATH, configBackup, "utf-8");
+              fs6.writeFileSync(CONFIG_PATH, configBackup, "utf-8");
             } catch {
             }
           }
@@ -1581,7 +1598,7 @@ function registerVersionMethods(api) {
 // src/relay-client.ts
 import { WebSocket as NodeWebSocket } from "ws";
 import crypto3 from "crypto";
-import fs7 from "fs";
+import fs8 from "fs";
 import path8 from "path";
 
 // src/e2e-crypto.ts
@@ -1663,24 +1680,24 @@ var E2ECrypto = class {
 
 // src/device-keys.ts
 import crypto2 from "crypto";
-import fs6 from "fs";
+import fs7 from "fs";
 import path7 from "path";
 var RELAY_DATA_DIR = path7.join(getOpenclawStateDir(), "squad-ceo-data", "relay");
 var RELAY_STATE_PATH = path7.join(RELAY_DATA_DIR, "squad-relay.json");
 var PENDING_APPROVAL_PATH = path7.join(RELAY_DATA_DIR, "pending-approval.json");
 function readRelayState() {
   try {
-    const raw = fs6.readFileSync(RELAY_STATE_PATH, "utf-8");
+    const raw = fs7.readFileSync(RELAY_STATE_PATH, "utf-8");
     return JSON.parse(raw);
   } catch {
     return {};
   }
 }
 function writeRelayState(state) {
-  if (!fs6.existsSync(RELAY_DATA_DIR)) {
-    fs6.mkdirSync(RELAY_DATA_DIR, { recursive: true });
+  if (!fs7.existsSync(RELAY_DATA_DIR)) {
+    fs7.mkdirSync(RELAY_DATA_DIR, { recursive: true });
   }
-  fs6.writeFileSync(RELAY_STATE_PATH, JSON.stringify(state, null, 2), { mode: 384 });
+  fs7.writeFileSync(RELAY_STATE_PATH, JSON.stringify(state, null, 2), { mode: 384 });
 }
 function toBase64Url(buf) {
   return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
@@ -1712,7 +1729,7 @@ function writeDeviceInfoFile(keys) {
     createdAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   try {
-    fs6.writeFileSync(infoPath, JSON.stringify(info, null, 2));
+    fs7.writeFileSync(infoPath, JSON.stringify(info, null, 2));
   } catch (err2) {
     console.error("[device-keys] Failed to write relay-device-info.json:", err2);
   }
@@ -1723,7 +1740,7 @@ function readOperatorToken() {
   const stateDir = getOpenclawStateDir();
   const configPath = path8.join(stateDir, "openclaw.json");
   try {
-    const raw = fs7.readFileSync(configPath, "utf-8");
+    const raw = fs8.readFileSync(configPath, "utf-8");
     const config = JSON.parse(raw);
     return config?.gateway?.auth?.token ?? config?.gateway?.remote?.token ?? config?.gateway?.token ?? null;
   } catch {
@@ -1739,7 +1756,7 @@ function readGatewayLocalWsConfig() {
   const stateDir = getOpenclawStateDir();
   const configPath = path8.join(stateDir, "openclaw.json");
   try {
-    const raw = fs7.readFileSync(configPath, "utf-8");
+    const raw = fs8.readFileSync(configPath, "utf-8");
     const config = JSON.parse(raw);
     const parsedPort = Number(config?.gateway?.port);
     if (Number.isFinite(parsedPort) && parsedPort > 0) {
@@ -2285,6 +2302,88 @@ function broadcastToUsers(event, payload) {
   relayClient?.broadcastToUsers(event, payload);
 }
 
+// src/layout.ts
+import fs9 from "fs";
+import path9 from "path";
+function resolveMaybeRelativePath(stateDir, p) {
+  if (path9.isAbsolute(p)) return path9.resolve(p);
+  return path9.resolve(stateDir, p);
+}
+function listWorkspaceFallbacks(stateDir) {
+  let entries;
+  try {
+    entries = fs9.readdirSync(stateDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.filter((entry) => entry.isDirectory() && (entry.name === "workspace" || entry.name.startsWith("workspace-"))).map((entry) => {
+    const agentId = entry.name === "workspace" ? "main" : entry.name.replace("workspace-", "");
+    const workspacePath = path9.join(stateDir, entry.name);
+    return {
+      agentId,
+      path: workspacePath,
+      source: "filesystem",
+      exists: true
+    };
+  });
+}
+function readOpenclawConfig(configPath) {
+  try {
+    const raw = fs9.readFileSync(configPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+function resolveGatewayLayout() {
+  const stateDir = getOpenclawStateDir();
+  const configPath = path9.join(stateDir, "openclaw.json");
+  const config = readOpenclawConfig(configPath);
+  const workspaces = [];
+  if (config?.agents?.main?.workspace || config?.agents?.main?.workspacePath) {
+    const rawPath = config.agents.main.workspace ?? config.agents.main.workspacePath;
+    if (rawPath) {
+      const resolvedPath = resolveMaybeRelativePath(stateDir, rawPath);
+      workspaces.push({
+        agentId: "main",
+        path: resolvedPath,
+        source: "config",
+        exists: fs9.existsSync(resolvedPath)
+      });
+    }
+  }
+  for (const agent of config?.agents?.list ?? []) {
+    const agentId = typeof agent.id === "string" && agent.id.trim() ? agent.id : null;
+    const rawPath = agent.workspace ?? agent.workspacePath;
+    if (!agentId || !rawPath) continue;
+    const resolvedPath = resolveMaybeRelativePath(stateDir, rawPath);
+    workspaces.push({
+      agentId,
+      path: resolvedPath,
+      source: "config",
+      exists: fs9.existsSync(resolvedPath)
+    });
+  }
+  const deduped = /* @__PURE__ */ new Map();
+  for (const ws of [...workspaces, ...listWorkspaceFallbacks(stateDir)]) {
+    if (!deduped.has(ws.agentId)) {
+      deduped.set(ws.agentId, ws);
+    }
+  }
+  const resolvedWorkspaces = Array.from(deduped.values());
+  const mainWorkspace = resolvedWorkspaces.find((ws) => ws.agentId === "main");
+  const defaultFileBrowserRoot = mainWorkspace?.path ?? stateDir;
+  return {
+    stateDir,
+    configPath,
+    mediaDir: path9.join(stateDir, "media"),
+    skillsDir: path9.join(stateDir, "skills"),
+    extensionsDir: path9.join(stateDir, "extensions"),
+    defaultFileBrowserRoot,
+    workspaces: resolvedWorkspaces
+  };
+}
+
 // src/index.ts
 function squadAppPlugin(api) {
   const toolExecutors = /* @__PURE__ */ new Map();
@@ -2367,6 +2466,17 @@ function squadAppPlugin(api) {
       respond(true, { tools: [...coreTools, ...groups, ...pluginTools] });
     }
   );
+  api.registerGatewayMethod(
+    "squad.layout.get",
+    async ({ respond }) => {
+      try {
+        respond(true, resolveGatewayLayout());
+      } catch (err2) {
+        const msg = err2 instanceof Error ? err2.message : String(err2);
+        respond(false, { errorMessage: msg });
+      }
+    }
+  );
   const relayState = readRelayState();
   const relayEnabled = !!(relayState.claimToken || relayState.roomId);
   if (relayEnabled) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "squad-openclaw",
-  "version": "2026.2.2017",
+  "version": "2026.2.2019",
   "description": "Entity registry, filesystem tools, and version management plugin for OpenClaw gateway",
   "type": "module",
   "main": "./dist/index.js",