squad-openclaw 2026.2.2007 → 2026.2.2008

package/README.md

@@ -11,12 +11,28 @@ OpenClaw gateway plugin for [Squad](https://squad.ceo) — provides entity regis
 | `sql_query` | Restricted SQLite query tool — `sqlite3` only, scoped to `~/.openclaw/squad-ceo-data/` |
 | `squad.version.check`, `squad.version.update` | Plugin version management and self-update |
 | `tools.invoke` | RPC-based tool invocation for relay mode — **only invokes this plugin's own tools**, each with its own security restrictions (see below) |
-| Cloud relay client | **Disabled by default (opt-in).** Connects outbound to `relay.squad.ceo` for remote browser access |
+| Cloud relay client | Connects outbound to `relay.squad.ceo` for remote browser access. **Only activates when a claim token or room ID exists** (see Relay Security below) |
+
+## 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.
+
+| Environment | Typical path | How it's resolved |
+|---|---|---|
+| Standard install | `~/.openclaw` | Default — `os.homedir() + "/.openclaw"` |
+| Docker | `/root/data/.openclaw` | `OPENCLAW_STATE_DIR=/root/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.
 
 ## 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.
 
+> **Note:** Throughout this section, `~/.openclaw` refers to the resolved state directory (see above). In Docker or custom installs, substitute the actual path set by `OPENCLAW_STATE_DIR`.
+
 ### Layer 1: Blocked Directories (hardcoded, non-configurable)
 
 These directories are **completely blocked** from all filesystem operations (read, write, list, delete, rename):
@@ -45,7 +61,7 @@ These directories are **completely blocked** from all filesystem operations (rea
 
 ### Layer 3: Allowed Roots (configurable, defaults to `~/.openclaw`)
 
-Filesystem operations are restricted to configured root directories. By default, only `~/.openclaw/` is accessible — covering all SPA needs:
+Filesystem operations are restricted to configured root directories. By default, only `~/.openclaw/` is accessible — covering all application needs:
 
 - `~/.openclaw/squad-ceo-data/` — entity databases, data files
 - `~/.openclaw/media/` — asset uploads
@@ -66,51 +82,114 @@ These files/directories cannot be written to, even if they fall within `allowedR
 
 ## Relay Security
 
-> **The cloud relay is DISABLED by default. No outbound connections are made unless the operator explicitly sets `relay.enabled: true`.** Installing this plugin alone does NOT create any network surface — the relay code is never executed until opted in.
+The cloud relay enables remote browser access to the gateway through `relay.squad.ceo`. This section explains the full architecture for security reviewers.
+
+### When Does the Relay Activate?
 
-The cloud relay enables remote browser access to the gateway through `relay.squad.ceo`.
+The relay client **only activates** when the relay state file (`~/.openclaw/squad-ceo-data/relay/squad-relay.json`) contains a `claimToken` or `roomId`. This file does not exist by default — it is created when the user runs the onboarding prompt from the Squad web app:
 
-### Opt-in Only
+```bash
+mkdir -p ~/.openclaw/squad-ceo-data/relay && \
+echo '{"claimToken":"<token>"}' > ~/.openclaw/squad-ceo-data/relay/squad-relay.json
+```
 
-The relay is **disabled by default** (`relay.enabled` defaults to `false`). The plugin entry point checks this flag **before** calling `startRelayClient()` — if the flag is not set or is `false`, no relay code runs, no WebSocket is opened, and no connection metadata is sent anywhere. The operator must explicitly enable it by setting `relay.enabled: true` in the plugin configuration.
+**If this file does not exist or contains neither key, no relay code runs, no WebSocket is opened, and no connection is made to any external server.** The plugin's entry point (`index.ts`) checks this before calling `startRelayClient()`.
 
-### Authentication
+The claim token is a short-lived, single-use code generated by the relay server for the authenticated user. It links this gateway to the user's Squad account. Once consumed, the relay returns a `roomId` for future reconnections, and the claim token is no longer needed.
 
-- **Browser to Relay:** JWT authentication (email/password or Google OAuth)
-- **Relay to Gateway:** Single-use claim token (24h expiry) for first connection, stored room ID for reconnection
-- Claim tokens are generated per-user during setup — **not** open access
+### How the Relay Connection Works
 
-### Device Pairing
+```
+┌──────────────┐        JWT auth         ┌──────────────────┐       outbound WS        ┌────────────────┐
+│  Browser SPA │ ◄──────────────────────► │  relay.squad.ceo │ ◄────────────────────────► │  relay-client  │
+│ (squad.ceo)  │   (wss://.../user)       │  (CF Worker + DO)│   (wss://.../gw)          │  (this plugin) │
+└──────────────┘                          └──────────────────┘                           └───────┬────────┘
+                                                                                                │
+                                                                              per-user local WS │
+                                                                              (ws://127.0.0.1:  │
+                                                                                      18789)    │
+                                                                                                ▼
+                                                                                     ┌──────────────────┐
+                                                                                     │ OpenClaw Gateway  │
+                                                                                     │  (localhost only) │
+                                                                                     └──────────────────┘
+```
 
-The relay-client's device identity must be **explicitly approved by the operator** before it can proxy user connections to the gateway. The plugin does **not** auto-pair or self-approve. During the onboarding flow, the AI guides the user through reading the device identity and confirming approval.
+1. **Browser → Relay:** The user authenticates with JWT (email/password or Google OAuth). The browser connects via WebSocket to the relay.
+2. **Relay-client → Relay:** The plugin opens an outbound WebSocket to `relay.squad.ceo` using the claim token (first connect) or stored room ID (reconnect). This is the **only** outbound connection the plugin makes.
+3. **Relay-client → Gateway:** For each browser user, the relay-client opens a **separate local WebSocket** to `ws://127.0.0.1:18789` (the gateway's loopback port). Each user gets an isolated session — the gateway sees them as individual clients.
 
-### E2E Encryption
+### What Data Crosses the Network (relay.squad.ceo)
 
-- **Protocol:** ECDH (P-256) key exchange + AES-256-GCM message encryption
-- **No plaintext fallback:** If encryption fails after E2E is established, messages are dropped — never sent as plaintext
-- **Status:** Implemented in the plugin. Currently disabled at the relay level (Durable Object) due to multi-tab session safety. When per-session E2E is enabled at the relay, the plugin is already hardened.
+The relay server is a message router. Here is exactly what it sees and does not see:
+
+| Data | Crosses relay? | Notes |
+|---|---|---|
+| Relay protocol envelopes (`relay.forward`, `relay.hello`, etc.) | **Yes** | Routing metadata only |
+| User ID (for message routing) | **Yes** | The relay routes by userId |
+| Gateway device ID and public key | **Yes** | Sent in `relay.hello` for identification |
+| Inner messages (gateway ↔ browser) | **Yes, but opaque** | Wrapped inside `relay.forward` envelopes |
+| **Operator auth token** | **NEVER** | Injected into the local WS connect request **after** the relay boundary (see below) |
+| **Device identity signature** | **NEVER** | Added to the local WS connect handshake only |
+| **Gateway connect handshake params** | **NEVER** | The `connect` request with auth + device identity is sent to `localhost:18789`, not the relay |
+| **Plaintext RPC payloads** (when E2E active) | **NEVER** | E2E encrypts before relay; relay sees ciphertext only |
+
+### Operator Token — Never Leaves the Server
 
-### Operator Token
+The operator token (`gateway.auth.token` in `~/.openclaw/openclaw.json`) is the most sensitive credential. Here is exactly how it flows:
 
-The relay-client reads `gateway.auth.token` from `~/.openclaw/openclaw.json` via direct `fs.readFileSync`. This is intentional and safe:
+1. **Read:** The relay-client reads the token from `~/.openclaw/openclaw.json` via `fs.readFileSync` at startup. This is equivalent to the gateway reading its own config — the plugin runs in the gateway's process.
 
-- The relay-client runs **server-side, in the gateway's own process** — equivalent to the gateway reading its own config
-- The token is **never sent to the relay server or the browser** — it is only injected into **local** `localhost:18789` WebSocket connections on the same machine
-- The token is **never exposed through the filesystem tool API** — `gateway.auth.*` is redacted in `filesystem.ts`
-- Direct file read is used because the plugin config API doesn't expose the full gateway config
+2. **Stored:** The token is held in memory (`this.config.operatorToken`) for the lifetime of the relay-client. It is **never written** to any file, log, or external service.
 
-**Token flow (important for security auditing):**
+3. **Used:** When a browser user's `connect` request arrives from the relay, the relay-client **injects** the operator token into the request **in memory**, then sends the modified request to `ws://127.0.0.1:18789` (localhost only). The relay server never sees this injection — it only sees the outer `relay.forward` envelope.
+
+4. **Protected via filesystem API:** The token is redacted from `~/.openclaw/openclaw.json` when read through this plugin's `fs_read` tool (`gateway.auth.*` → `"[REDACTED]"`). Remote clients (browser, agents) cannot read the token through any tool this plugin provides.
 
 ```
-Browser ──[connect request]──> relay.squad.ceo ──[relay.forward]──> relay-client
+Browser ──[connect request]──► relay.squad.ceo ──[relay.forward]──► relay-client
                                                                         │
                                Token is injected HERE, in memory,       │
                                into the connect request.                │
                                                                         ▼
-                               relay-client ──[modified request]──> localhost:18789 (gateway)
+                               relay-client ──[modified request]──► localhost:18789 (gateway)
 ```
 
-The relay server only sees the outer `relay.forward` envelope. It **never** receives the modified request containing the token. The token injection happens entirely within the relay-client process, and the modified message is sent over a **local loopback** connection to the gateway. A compromised relay server cannot intercept the operator token because it never traverses the relay — it only exists on the `localhost:18789` path.
+**A compromised relay server cannot intercept the operator token** because the token is injected after the relay boundary — it only exists on the `localhost:18789` path between the relay-client and the gateway, both running on the same machine.
+
+### Device Identity and Auto-Pairing
+
+The relay-client generates an ed25519 keypair on first run (`device-keys.ts`). The device identity is used to sign the `connect` handshake to the local gateway using the v2 signature protocol:
+
+- **Signature payload:** `v2|deviceId|clientId|clientMode|role|scopes|signedAtMs|token|nonce` (pipe-delimited)
+- **deviceId:** SHA-256 fingerprint of the ed25519 public key (hex, 64 chars)
+- **publicKey:** base64url-encoded ed25519 public key (no padding)
+
+The gateway **auto-pairs** devices that connect with a valid operator token and a correctly signed device identity. No manual `openclaw devices approve` step is required. The authorization chain is:
+
+1. The **user** authenticates with the Squad web app (JWT via email/password or Google OAuth)
+2. The user generates a **claim token** (short-lived, single-use) and gives it to the gateway via the onboarding prompt
+3. The plugin starts the relay-client, which connects to the relay with the claim token
+4. When a browser user connects, the relay-client signs the connect handshake with its device key and the operator token
+5. The gateway validates the signature and auto-pairs the device
+
+The claim token is the user's explicit consent to link their gateway to their Squad account. The operator token is the proof of authorization on the gateway side. Together, they form a two-sided trust chain without requiring manual device approval.
+
+### E2E Encryption
+
+- **Protocol:** ECDH (P-256) key exchange + AES-256-GCM message encryption
+- **No plaintext fallback:** If encryption fails after E2E is established, messages are **dropped** — never sent as plaintext. This is enforced in both `routeFromGateway()` and `broadcastToUsers()`.
+- **Status:** Implemented in the plugin. Currently disabled at the relay level (Durable Object) due to multi-tab session safety — the relay blocks E2E key exchange to prevent mismatched keys across tabs. When per-session E2E is enabled at the relay, the plugin is already hardened.
+
+### Authentication Chain Summary
+
+For a browser user's RPC call to reach the gateway through the relay, **all of the following must be valid:**
+
+1. **Browser JWT** — user authenticated with relay.squad.ceo
+2. **Relay pairing** — user's account is paired with this gateway's Durable Object (via claim token)
+3. **Relay-client connected** — plugin's outbound WS to relay is alive
+4. **Gateway connect handshake** — relay-client's device identity + operator token accepted by local gateway
+5. **Tool-level security** — each tool enforces its own restrictions (blocked dirs, redaction, write protection, SQL path limits)
 
 ## Remote Tool Invocation (`tools.invoke`)
 
@@ -125,8 +204,6 @@ The `tools.invoke` gateway method allows the browser to call plugin tools over W
 
 It **cannot** invoke gateway core tools (`exec`, `bash`, `read`, `write`, `web_fetch`, etc.) — only the tools this plugin registers via `api.registerTool()`. Every invoked tool enforces its own security restrictions independently — `tools.invoke` is just a transport layer, not a privilege escalation.
 
-**Authentication chain for relay access:** Browser JWT → relay claim token → operator-approved device pairing → operator auth token (localhost only). All four must be valid for a `tools.invoke` call to reach the gateway.
-
 ## SQL Query Tool
 
 > **`sql_query` can only access the plugin's own application data** in `~/.openclaw/squad-ceo-data/`. It cannot read or modify any other files on the system — not system databases, not user documents, not gateway configuration.
@@ -154,9 +231,7 @@ Configure in your gateway's `openclaw.json` under the plugin section:
 
 | Key | Type | Default | Description |
 |---|---|---|---|
-| `relay.enabled` | `boolean` | `false` | Enable cloud relay. Opt-in required. |
-| `relay.url` | `string` | `wss://relay.squad.ceo` | Cloud relay WebSocket URL |
-| `fs.allowedRoots` | `string[]` | `["~/.openclaw"]` | Restrict filesystem operations to these directories |
+| `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. |
 
 ## Source Code
 
@@ -165,7 +240,9 @@ Configure in your gateway's `openclaw.json` under the plugin section:
 - **Security-critical files:**
   - `src/filesystem.ts` — path blocking, redaction, write protection
   - `src/sql.ts` — restricted SQL execution
-  - `src/relay-client.ts` — relay authentication, E2E encryption, device identity
+  - `src/relay-client.ts` — relay authentication, E2E encryption, device identity, operator token handling
+  - `src/device-keys.ts` — ed25519 key generation, device identity management
+  - `src/e2e-crypto.ts` — ECDH key exchange, AES-256-GCM encryption
 
 ## License
 

package/dist/index.js

@@ -104,7 +104,7 @@ function registerAgentMethods(api) {
 
 // src/entities.ts
 import { Type as T } from "@sinclair/typebox";
-import path3 from "path";
+import path4 from "path";
 import fs3 from "fs";
 
 // src/watcher.ts
@@ -361,20 +361,29 @@ function startWatcher(configDir, onFsChange) {
 
 // src/filesystem.ts
 import fs2 from "fs";
+import path3 from "path";
+
+// src/paths.ts
 import path2 from "path";
+import os from "os";
+function getOpenclawStateDir() {
+  return process.env.OPENCLAW_STATE_DIR || path2.join(os.homedir(), ".openclaw");
+}
+
+// src/filesystem.ts
 var HOME_DIR = process.env.HOME ?? "/root";
-var OPENCLAW_DIR = path2.join(HOME_DIR, ".openclaw");
+var OPENCLAW_DIR = getOpenclawStateDir();
 var SENSITIVE_BLOCKED_DIRS = [
-  path2.join(OPENCLAW_DIR, "credentials"),
-  path2.join(OPENCLAW_DIR, "devices"),
-  path2.join(OPENCLAW_DIR, "identity")
+  path3.join(OPENCLAW_DIR, "credentials"),
+  path3.join(OPENCLAW_DIR, "devices"),
+  path3.join(OPENCLAW_DIR, "identity")
 ];
 var SENSITIVE_BLOCKED_FILES = [
-  path2.join(OPENCLAW_DIR, "squad-ceo-data", "relay", "squad-relay.json")
+  path3.join(OPENCLAW_DIR, "squad-ceo-data", "relay", "squad-relay.json")
 ];
 function isSensitivePath(resolvedPath) {
   for (const blocked of SENSITIVE_BLOCKED_DIRS) {
-    if (resolvedPath === blocked || resolvedPath.startsWith(blocked + path2.sep)) {
+    if (resolvedPath === blocked || resolvedPath.startsWith(blocked + path3.sep)) {
       return true;
     }
   }
@@ -383,7 +392,7 @@ function isSensitivePath(resolvedPath) {
       return true;
     }
   }
-  if (path2.dirname(resolvedPath) === OPENCLAW_DIR && resolvedPath.endsWith(".bak")) {
+  if (path3.dirname(resolvedPath) === OPENCLAW_DIR && resolvedPath.endsWith(".bak")) {
     return true;
   }
   return false;
@@ -432,20 +441,20 @@ function redactOpenclawJson(rawContent) {
   return JSON.stringify(config, null, 2);
 }
 function isOpenclawJson(resolvedPath) {
-  return path2.basename(resolvedPath) === OPENCLAW_JSON_FILENAME && resolvedPath.startsWith(OPENCLAW_DIR);
+  return path3.basename(resolvedPath) === OPENCLAW_JSON_FILENAME && resolvedPath.startsWith(OPENCLAW_DIR);
 }
 function expandHome(p) {
   if (p.startsWith("~/") || p === "~") {
-    return path2.join(HOME_DIR, p.slice(1));
+    return path3.join(HOME_DIR, p.slice(1));
   }
   return p;
 }
 function validatePath(p, allowedRoots) {
-  const resolved = path2.resolve(expandHome(p));
+  const resolved = path3.resolve(expandHome(p));
   if (!allowedRoots || allowedRoots.length === 0) return resolved;
   const allowed = allowedRoots.some((root) => {
-    const resolvedRoot = path2.resolve(expandHome(root));
-    return resolved === resolvedRoot || resolved.startsWith(resolvedRoot + path2.sep);
+    const resolvedRoot = path3.resolve(expandHome(root));
+    return resolved === resolvedRoot || resolved.startsWith(resolvedRoot + path3.sep);
   });
   if (!allowed) {
     throw new Error(`Path "${p}" is outside allowed roots`);
@@ -486,7 +495,7 @@ function listDir(dirPath, opts) {
   const results = [];
   for (const dirent of dirents) {
     if (!opts.includeHidden && dirent.name.startsWith(".")) continue;
-    const entryPath = path2.join(dirPath, dirent.name);
+    const entryPath = path3.join(dirPath, dirent.name);
     let type = "other";
     if (dirent.isFile()) type = "file";
     else if (dirent.isDirectory()) type = "directory";
@@ -593,7 +602,7 @@ function registerFilesystemTools(api) {
         const encoding = params.encoding ?? "utf-8";
         const mkdir = params.mkdir !== false;
         if (mkdir) {
-          fs2.mkdirSync(path2.dirname(filePath), { recursive: true });
+          fs2.mkdirSync(path3.dirname(filePath), { recursive: true });
         }
         fs2.writeFileSync(filePath, content, encoding);
         const stat = fs2.statSync(filePath);
@@ -793,10 +802,10 @@ function scanAgents(configDir) {
   );
   for (const dir of workspaceDirs) {
     const agentId = dir.name === "workspace" ? "main" : dir.name.replace("workspace-", "");
-    const workspacePath = path3.join(configDir, dir.name);
+    const workspacePath = path4.join(configDir, dir.name);
     let name = agentId;
     const metadata = { workspacePath };
-    const identityPath = path3.join(workspacePath, "IDENTITY.md");
+    const identityPath = path4.join(workspacePath, "IDENTITY.md");
     try {
       const content = fs3.readFileSync(identityPath, "utf-8");
       const parsed = parseIdentityName(content);
@@ -804,7 +813,7 @@ function scanAgents(configDir) {
     } catch {
     }
     if (name === agentId) {
-      const agentJsonPath = path3.join(workspacePath, "agent.json");
+      const agentJsonPath = path4.join(workspacePath, "agent.json");
       try {
         const raw = fs3.readFileSync(agentJsonPath, "utf-8");
         const config = JSON.parse(raw);
@@ -831,7 +840,7 @@ function scanAgents(configDir) {
 }
 function scanSkills(configDir) {
   const now = Date.now();
-  const globalSkillsDir = path3.join(configDir, "skills");
+  const globalSkillsDir = path4.join(configDir, "skills");
   scanSkillsDir(globalSkillsDir, "global", now);
   let entries;
   try {
@@ -844,7 +853,7 @@ function scanSkills(configDir) {
       continue;
     }
     const agentId = dir.name === "workspace" ? "main" : dir.name.replace("workspace-", "");
-    const agentSkillsDir = path3.join(configDir, dir.name, "skills");
+    const agentSkillsDir = path4.join(configDir, dir.name, "skills");
     scanSkillsDir(agentSkillsDir, agentId, now);
   }
 }
@@ -858,12 +867,12 @@ function scanSkillsDir(skillsDir, scope, now) {
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const skillKey = entry.name;
-    const skillPath = path3.join(skillsDir, skillKey);
+    const skillPath = path4.join(skillsDir, skillKey);
     let name = skillKey;
     for (const manifestName of ["manifest.json", "package.json"]) {
       try {
         const raw = fs3.readFileSync(
-          path3.join(skillPath, manifestName),
+          path4.join(skillPath, manifestName),
           "utf-8"
         );
         const manifest = JSON.parse(raw);
@@ -890,7 +899,7 @@ function scanSkillsDir(skillsDir, scope, now) {
 }
 function scanPlugins2(configDir) {
   const now = Date.now();
-  const extensionsDir = path3.join(configDir, "extensions");
+  const extensionsDir = path4.join(configDir, "extensions");
   let entries;
   try {
     entries = fs3.readdirSync(extensionsDir, { withFileTypes: true });
@@ -899,8 +908,8 @@ function scanPlugins2(configDir) {
   }
   for (const dir of entries) {
     if (!dir.isDirectory()) continue;
-    const pluginDir = path3.join(extensionsDir, dir.name);
-    const manifestPath = path3.join(pluginDir, "openclaw.plugin.json");
+    const pluginDir = path4.join(extensionsDir, dir.name);
+    const manifestPath = path4.join(pluginDir, "openclaw.plugin.json");
     try {
       const raw = fs3.readFileSync(manifestPath, "utf-8");
       const manifest = JSON.parse(raw);
@@ -926,7 +935,7 @@ function scanTools(configDir) {
   const now = Date.now();
   try {
     const raw = fs3.readFileSync(
-      path3.join(configDir, "openclaw.json"),
+      path4.join(configDir, "openclaw.json"),
       "utf-8"
     );
     const config = JSON.parse(raw);
@@ -977,12 +986,12 @@ var MIME_MAP = {
   ".gz": "application/gzip"
 };
 function getMimeType(filename) {
-  const ext = path3.extname(filename).toLowerCase();
+  const ext = path4.extname(filename).toLowerCase();
   return MIME_MAP[ext] ?? "application/octet-stream";
 }
 function scanMedia(configDir) {
   const now = Date.now();
-  const mediaDir = path3.join(configDir, "media");
+  const mediaDir = path4.join(configDir, "media");
   scanMediaDir(mediaDir, now);
 }
 function scanMediaDir(dirPath, now) {
@@ -994,7 +1003,7 @@ function scanMediaDir(dirPath, now) {
   }
   for (const entry of entries) {
     if (entry.name.startsWith(".")) continue;
-    const entryPath = path3.join(dirPath, entry.name);
+    const entryPath = path4.join(dirPath, entry.name);
     if (isSensitivePath(entryPath)) continue;
     if (entry.isDirectory()) {
       registrySet({
@@ -1044,7 +1053,7 @@ function fullScan(configDir) {
   scanMedia(configDir);
 }
 function registerEntityTools(api, onFsChange) {
-  const configDir = process.env.HOME + "/.openclaw";
+  const configDir = getOpenclawStateDir();
   api.registerTool({
     name: "entity_list",
     description: "List all entities in the registry, optionally filtered by type. Returns lightweight entity data for @mention autocomplete.",
@@ -1132,18 +1141,18 @@ function registerEntityTools(api, onFsChange) {
 
 // src/sql.ts
 import { execFile } from "child_process";
-import path4 from "path";
+import path5 from "path";
 import fs4 from "fs";
 import { Type as T2 } from "@sinclair/typebox";
 var HOME_DIR2 = process.env.HOME ?? "/root";
-var ALLOWED_DATA_DIR = path4.join(HOME_DIR2, ".openclaw", "squad-ceo-data");
+var ALLOWED_DATA_DIR = path5.join(getOpenclawStateDir(), "squad-ceo-data");
 function validateDbPath(dbPath) {
   let expanded = dbPath;
   if (expanded.startsWith("~/") || expanded === "~") {
-    expanded = path4.join(HOME_DIR2, expanded.slice(1));
+    expanded = path5.join(HOME_DIR2, expanded.slice(1));
   }
-  const resolved = path4.resolve(expanded);
-  if (resolved !== ALLOWED_DATA_DIR && !resolved.startsWith(ALLOWED_DATA_DIR + path4.sep)) {
+  const resolved = path5.resolve(expanded);
+  if (resolved !== ALLOWED_DATA_DIR && !resolved.startsWith(ALLOWED_DATA_DIR + path5.sep)) {
     throw new Error(
       `Access denied: database path must be within ~/.openclaw/squad-ceo-data/`
     );
@@ -1217,17 +1226,13 @@ function registerSqlTools(api) {
 // src/version.ts
 import { execSync as execSync2 } from "child_process";
 import fs5 from "fs";
-import path5 from "path";
+import path6 from "path";
 import { fileURLToPath } from "url";
 var PACKAGE_NAME = "squad-openclaw";
-var CONFIG_PATH = path5.join(
-  process.env.HOME ?? "/root",
-  ".openclaw",
-  "openclaw.json"
-);
+var CONFIG_PATH = path6.join(getOpenclawStateDir(), "openclaw.json");
 function getCurrentVersion() {
   const thisFile = fileURLToPath(import.meta.url);
-  const pkgPath = path5.resolve(path5.dirname(thisFile), "..", "package.json");
+  const pkgPath = path6.resolve(path6.dirname(thisFile), "..", "package.json");
   try {
     const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf-8"));
     return pkg.version ?? "0.0.0";
@@ -1354,8 +1359,7 @@ function registerVersionMethods(api) {
 import { WebSocket as NodeWebSocket } from "ws";
 import crypto3 from "crypto";
 import fs7 from "fs";
-import path7 from "path";
-import os2 from "os";
+import path8 from "path";
 
 // src/e2e-crypto.ts
 import crypto from "crypto";
@@ -1437,11 +1441,10 @@ var E2ECrypto = class {
 // src/device-keys.ts
 import crypto2 from "crypto";
 import fs6 from "fs";
-import path6 from "path";
-import os from "os";
-var RELAY_DATA_DIR = path6.join(os.homedir(), ".openclaw", "squad-ceo-data", "relay");
-var RELAY_STATE_PATH = path6.join(RELAY_DATA_DIR, "squad-relay.json");
-var PENDING_APPROVAL_PATH = path6.join(RELAY_DATA_DIR, "pending-approval.json");
+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");
@@ -1476,8 +1479,8 @@ function loadOrCreateRelayDeviceKeys() {
   return keys;
 }
 function writeDeviceInfoFile(keys) {
-  const stateDir = process.env.OPENCLAW_STATE_DIR || path6.join(os.homedir(), ".openclaw");
-  const infoPath = path6.join(stateDir, "squad-ceo-data", "relay", "relay-device-info.json");
+  const stateDir = getOpenclawStateDir();
+  const infoPath = path7.join(stateDir, "squad-ceo-data", "relay", "relay-device-info.json");
   const info = {
     deviceId: keys.deviceId,
     publicKey: keys.publicKey,
@@ -1494,8 +1497,8 @@ function writeDeviceInfoFile(keys) {
 
 // src/relay-client.ts
 function readOperatorToken() {
-  const stateDir = process.env.OPENCLAW_STATE_DIR || path7.join(os2.homedir(), ".openclaw");
-  const configPath = path7.join(stateDir, "openclaw.json");
+  const stateDir = getOpenclawStateDir();
+  const configPath = path8.join(stateDir, "openclaw.json");
   try {
     const raw = fs7.readFileSync(configPath, "utf-8");
     const config = JSON.parse(raw);
@@ -1847,9 +1850,8 @@ var RelayClient = class {
       console.log(`[relay-client] Local WS for user ${userId} closed: ${code} ${reasonStr}`);
       if (code === 1008) {
         console.error(
-          `[relay-client] Device not paired with gateway. To approve, run on the gateway machine:
-  openclaw devices approve
-Or follow the onboarding instructions in the Squad web app.
+          `[relay-client] Gateway rejected device identity (code 1008). The gateway auto-pairs devices with a valid operator token, so this usually means the operator token is missing, expired, or incorrect.
+Check: ~/.openclaw/openclaw.json \u2192 gateway.auth.token
 Device ID: ${this.deviceKeys.deviceId}`
         );
       }
@@ -1927,7 +1929,7 @@ Device ID: ${this.deviceKeys.deviceId}`
       status: "pending"
     });
     console.log(
-      `[relay-client] Pairing request pending for ${email}. Approve with: openclaw nodes approve (or configure relay.autoApprove)`
+      `[relay-client] Pairing request pending for ${email}. The gateway will auto-pair this device if the operator token is valid.`
     );
   }
   // ── E2E Key Exchange ──

package/openclaw.plugin.json

@@ -11,16 +11,6 @@
         "items": { "type": "string" },
         "default": ["~/.openclaw"],
         "description": "Restrict filesystem operations to these directories. Defaults to [\"~/.openclaw\"]. Hardcoded blocks on credentials/, devices/, identity/, relay/squad-relay.json, and .bak files always apply."
-      },
-      "relay.enabled": {
-        "type": "boolean",
-        "default": false,
-        "description": "Enable cloud relay for remote browser access. Disabled by default — opt-in required."
-      },
-      "relay.url": {
-        "type": "string",
-        "default": "wss://relay.squad.ceo",
-        "description": "Cloud relay WebSocket URL. Defaults to wss://relay.squad.ceo."
       }
     }
   }

package/package.json

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