squad-openclaw 2026.2.2017 → 2026.2.2018

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

@@ -367,7 +367,7 @@ import path3 from "path";
 import path2 from "path";
 import os from "os";
 function getOpenclawStateDir() {
-  return process.env.OPENCLAW_STATE_DIR || path2.join(os.homedir(), ".openclaw");
+  return process.env.OPENCLAW_STATE_DIR || process.env.OPENCLAW_DIR || path2.join(os.homedir(), ".openclaw");
 }
 
 // src/filesystem.ts
@@ -526,7 +526,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",
@@ -2285,6 +2285,88 @@ function broadcastToUsers(event, payload) {
   relayClient?.broadcastToUsers(event, payload);
 }
 
+// src/layout.ts
+import fs8 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 = fs8.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 = fs8.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: fs8.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: fs8.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 +2449,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.2018",
   "description": "Entity registry, filesystem tools, and version management plugin for OpenClaw gateway",
   "type": "module",
   "main": "./dist/index.js",