@clawling/clawchat-plugin-openclaw 2026.9.8-2 → 2026.9.10-1

package/dist/src/client.js

@@ -2,8 +2,28 @@ import { createHash } from "node:crypto";
 import os from "node:os";
 import { createClawChatClient } from "./ws-client.js";
 import { CHANNEL_ID } from "./config.js";
-export function resolveOpenclawClawlingDeviceId(account) {
-    const material = [CHANNEL_ID, account.accountId, account.userId, os.hostname()].join("\0");
+import { resolveStateDirFromEnv } from "./state-paths.js";
+/**
+ * Derive this instance's `device_id` from stable, per-instance material.
+ *
+ * The state dir is part of the material because it is the ONLY input that
+ * distinguishes two OpenClaw instances on one host: `openclaw --profile <name>`
+ * isolates an instance by pointing it at `~/.openclaw-<name>` (host
+ * `src/cli/profile.ts:133-146`), but `accountId` is a constant and `hostname()`
+ * is shared. Two profiles that end up on the SAME ClawChat identity — trivially
+ * easy, since an exported `CLAWCHAT_TOKEN` is inherited by a second profile
+ * whose own channel config is still empty (`config.ts` env fallbacks) — would
+ * otherwise present a byte-identical device id and evict each other forever
+ * (`ws-client.ts` close codes 4001/4002 and the escalating takeover floor).
+ *
+ * Existing installs are unaffected: once the server has resolved a device id it
+ * is persisted and replayed as `deviceIdOverride` (`runtime.ts`
+ * `getLastResolvedDeviceId` → `markConnectionReady`), so this derivation only
+ * governs a first-ever connect.
+ */
+export function resolveOpenclawClawlingDeviceId(account, opts = {}) {
+    const stateDir = opts.stateDir?.trim() || resolveStateDirFromEnv();
+    const material = [CHANNEL_ID, account.accountId, account.userId, os.hostname(), stateDir].join("\0");
     const digest = createHash("sha256").update(material).digest("hex").slice(0, 24);
     return `${CHANNEL_ID}-${digest}`;
 }

package/dist/src/liveware-cli.js

@@ -10,6 +10,33 @@ export function livewareDir(stateDir) {
     const root = stateDir ?? resolveStateDir();
     return path.join(root, "clawchat", "liveware");
 }
+/**
+ * Private HOME for the liveware CLI: `<stateDir>/clawchat/liveware-home`.
+ *
+ * The CLI keeps its login credentials in `$HOME/.clawling`, which is
+ * host-global. Two OpenClaw instances on one box (`openclaw --profile <name>`,
+ * each with its own state dir but the same OS account) each run
+ * `liveware login --access-token <their own>`, so the last writer wins and the
+ * earlier instance's long-lived `liveware agent` daemon ends up authenticated
+ * as the OTHER account's user. Pointing HOME at the state dir makes the
+ * credential store per-instance, which is the same isolation the rest of the
+ * plugin already gets for free.
+ *
+ * Migration is automatic: `livewareLogin` runs on every bootstrap AND (best
+ * effort) on every relaunch, so an existing install simply re-logs into its new
+ * private home on the next start.
+ */
+export function livewareCliHomeDir(stateDir) {
+    const root = stateDir ?? resolveStateDir();
+    return path.join(root, "clawchat", "liveware-home");
+}
+/**
+ * Environment for every liveware CLI invocation: the ambient env with HOME
+ * (and Windows' USERPROFILE) redirected to {@link livewareCliHomeDir}.
+ */
+export function livewareCliEnv(cliHome, baseEnv = process.env) {
+    return { ...baseEnv, HOME: cliHome, USERPROFILE: cliHome };
+}
 /** Local filename for the downloaded binary; Windows needs a .exe suffix. */
 export function livewareBinaryName(plat = process.platform) {
     return plat === "win32" ? "liveware.exe" : "liveware";

package/dist/src/liveware-sample.js

@@ -7,8 +7,10 @@
 import crypto from "node:crypto";
 import { execFile as nodeExecFile, spawn as nodeSpawn } from "node:child_process";
 import fs from "node:fs";
+import net from "node:net";
 import path from "node:path";
 import { DEFAULT_SKILLS_REF, OFFICIAL_SKILLS_BASE } from "./skill-update.js";
+import { livewareCliEnv } from "./liveware-cli.js";
 export const LIVEWARES_TARGET = "openclaw";
 export const LIVEWARE_SAMPLE_ID = "liveware-sample";
 export const LIVEWARE_SAMPLE_APP_NAME = "Liveware Sample";
@@ -260,6 +262,45 @@ function waitForOutput(child, match, timeoutMs, label) {
         child.on("exit", onExit);
     });
 }
+const probeLoopbackPort = (port) => new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(null));
+    srv.listen({ port, host: "127.0.0.1", exclusive: true }, () => {
+        const addr = srv.address();
+        const bound = addr && typeof addr === "object" ? addr.port : null;
+        srv.close(() => resolve(bound));
+    });
+});
+/**
+ * Choose the port the sample server should bind.
+ *
+ * `DEFAULT_SAMPLE_PORT` used to be passed to the child unconditionally, so a
+ * second OpenClaw instance on the same host (`openclaw --profile <name>`) lost
+ * the bind race, never printed its `{"port"…}` line, and burnt the whole
+ * `START_RETRY_DELAYS_MS` ladder before going dormant — permanently, because
+ * the port persisted in BOTH state dirs was the same constant.
+ *
+ * `preferred` is still tried first so a single-instance install keeps its
+ * familiar port and its existing tunnel binding; anything else falls back to a
+ * kernel-assigned ephemeral port. A changed port costs nothing: bootstrap and
+ * relaunch both re-run `tunnel bind` with the actual port and only re-register
+ * with ClawChat when the resulting public URL changed.
+ *
+ * The probe closes its socket before the child binds, so there is a small race
+ * with an unrelated process. That is inherent to pre-allocating a port for a
+ * child, and a lost race is a transient start failure the retry ladder handles.
+ */
+export async function resolveSamplePort(preferred, probeFn = probeLoopbackPort) {
+    if (typeof preferred === "number" && preferred > 0) {
+        const kept = await probeFn(preferred);
+        if (kept)
+            return kept;
+    }
+    const ephemeral = await probeFn(0);
+    if (!ephemeral)
+        throw new Error("liveware-sample: cannot allocate a local port");
+    return ephemeral;
+}
 export async function startSampleServer(opts) {
     const spawnFn = opts.spawnFn ?? nodeSpawn;
     const args = [path.join(opts.appDir, "server.mjs"), "--dir", opts.appDir, "--port", String(opts.port)];
@@ -299,7 +340,7 @@ export function parseTunnelPublicUrl(output) {
 export async function tunnelBind(opts) {
     const execFileFn = opts.execFileFn ?? nodeExecFile;
     const output = await new Promise((resolve, reject) => {
-        execFileFn(opts.livewarePath, ["tunnel", "bind", opts.appId, `http://127.0.0.1:${opts.port}`], { timeout: CLI_TIMEOUT_MS }, (err, out, errOut) => {
+        execFileFn(opts.livewarePath, ["tunnel", "bind", opts.appId, `http://127.0.0.1:${opts.port}`], { timeout: CLI_TIMEOUT_MS, ...(opts.env ? { env: opts.env } : {}) }, (err, out, errOut) => {
             if (err) {
                 reject(new Error(`liveware tunnel bind failed: ${errOut || out || String(err)}`.trim()));
                 return;
@@ -333,14 +374,36 @@ export function parseAgentReady(output) {
  */
 export async function startTunnelAgent(opts) {
     const spawnFn = opts.spawnFn ?? nodeSpawn;
-    const child = spawnFn(opts.livewarePath, ["agent"], { stdio: ["ignore", "pipe", "pipe"] });
+    const child = spawnFn(opts.livewarePath, ["agent"], { stdio: ["ignore", "pipe", "pipe"], ...(opts.env ? { env: opts.env } : {}) });
     await waitForOutput(child, (acc) => parseAgentReady(acc), opts.timeoutMs ?? TUNNEL_START_TIMEOUT_MS, "liveware agent start");
     return { child };
 }
+/** Where the liveware CLI keeps its login state, relative to its `HOME`. */
+const LIVEWARE_CREDENTIAL_DIRNAME = ".clawling";
+/**
+ * True when the liveware CLI has usable cached credentials under `cliHome`.
+ *
+ * Tolerates either shape the CLI might use: a credential file (non-empty) or a
+ * directory (non-empty). Anything unreadable answers "no" — the caller's only
+ * use is deciding whether it is safe to skip a login, and guessing "yes" there
+ * is exactly the failure this check exists to prevent.
+ */
+export async function hasCachedLivewareCredentials(cliHome) {
+    const target = path.join(cliHome, LIVEWARE_CREDENTIAL_DIRNAME);
+    try {
+        const stat = await fs.promises.stat(target);
+        if (stat.isDirectory())
+            return (await fs.promises.readdir(target)).length > 0;
+        return stat.size > 0;
+    }
+    catch {
+        return false;
+    }
+}
 export async function livewareLogin(opts) {
     const execFileFn = opts.execFileFn ?? nodeExecFile;
     await new Promise((resolve, reject) => {
-        execFileFn(opts.livewarePath, ["login", "--access-token", opts.token], { timeout: CLI_TIMEOUT_MS }, (err, stdout, stderr) => {
+        execFileFn(opts.livewarePath, ["login", "--access-token", opts.token], { timeout: CLI_TIMEOUT_MS, ...(opts.env ? { env: opts.env } : {}) }, (err, stdout, stderr) => {
             if (!err) {
                 resolve();
                 return;
@@ -466,7 +529,7 @@ function findNamedIdDeep(value, name) {
 export async function livewareAppFindByName(opts) {
     const execFileFn = opts.execFileFn ?? nodeExecFile;
     const stdout = await new Promise((resolve) => {
-        execFileFn(opts.livewarePath, ["app", "list"], { timeout: CLI_TIMEOUT_MS }, (err, out, errOut) => {
+        execFileFn(opts.livewarePath, ["app", "list"], { timeout: CLI_TIMEOUT_MS, ...(opts.env ? { env: opts.env } : {}) }, (err, out, errOut) => {
             if (err) {
                 opts.log?.debug?.(`liveware-sample: app list failed; falling back to app create: ${String(errOut || out || err)}`);
                 resolve(null);
@@ -480,7 +543,7 @@ export async function livewareAppFindByName(opts) {
 export async function livewareAppCreate(opts) {
     const execFileFn = opts.execFileFn ?? nodeExecFile;
     const stdout = await new Promise((resolve, reject) => {
-        execFileFn(opts.livewarePath, ["app", "create", opts.name], { timeout: CLI_TIMEOUT_MS }, (err, out, errOut) => {
+        execFileFn(opts.livewarePath, ["app", "create", opts.name], { timeout: CLI_TIMEOUT_MS, ...(opts.env ? { env: opts.env } : {}) }, (err, out, errOut) => {
             if (err) {
                 reject(new Error(`liveware app create failed: ${errOut || out || String(err)}`.trim()));
                 return;
@@ -629,6 +692,27 @@ export class LivewareSampleSupervisor {
         this.killChildren();
         return true;
     }
+    /**
+     * Environment for every liveware CLI invocation in this flow. Creates the
+     * private HOME first: the CLI writes `<HOME>/.clawling` on login and a
+     * missing parent would fail the very step that isolates the credentials.
+     * Falls back to the ambient env when the dir cannot be created, so an
+     * unwritable state dir degrades to the old shared-HOME behavior instead of
+     * breaking the sample outright.
+     */
+    async ensureCliEnv() {
+        const cliHome = this.deps.cliHome?.trim();
+        if (!cliHome)
+            return undefined;
+        try {
+            await fs.promises.mkdir(cliHome, { recursive: true });
+        }
+        catch (err) {
+            this.deps.log?.warn?.(`liveware-sample: cannot create private CLI home ${cliHome}; using ambient HOME: ${String(err)}`);
+            return undefined;
+        }
+        return livewareCliEnv(cliHome);
+    }
     async bootstrap() {
         const { deps } = this;
         if (this.stopped)
@@ -656,14 +740,17 @@ export class LivewareSampleSupervisor {
         });
         if (this.bailIfStopped())
             return;
+        const cliEnv = await this.ensureCliEnv();
         const server = await startSampleServer({
-            appDir, port: DEFAULT_SAMPLE_PORT, spawnFn: deps.spawnFn,
+            appDir,
+            port: await resolveSamplePort(DEFAULT_SAMPLE_PORT, deps.probePortFn),
+            spawnFn: deps.spawnFn,
             agentUserId: deps.resolveAgentUserId?.() ?? null,
         });
         this.serverChild = server.child;
         if (this.bailIfStopped())
             return;
-        await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn });
+        await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn, env: cliEnv });
         // Reuse an app we already own before minting another one. `app create` is not
         // idempotent and nothing here ever reconciled against the liveware side, so
         // every bootstrap that died past this point (no row was written until the very
@@ -671,6 +758,7 @@ export class LivewareSampleSupervisor {
         // app quota. Best-effort: an unreadable list falls through to `app create`.
         const existingAppId = await livewareAppFindByName({
             livewarePath, name: LIVEWARE_SAMPLE_APP_NAME, execFileFn: deps.execFileFn, log: deps.log,
+            env: cliEnv,
         });
         if (this.bailIfStopped())
             return;
@@ -678,7 +766,7 @@ export class LivewareSampleSupervisor {
             deps.log?.debug?.(`liveware-sample: reusing existing liveware app ${existingAppId}`);
         }
         const appId = existingAppId ?? await livewareAppCreate({
-            livewarePath, name: LIVEWARE_SAMPLE_APP_NAME, execFileFn: deps.execFileFn,
+            livewarePath, name: LIVEWARE_SAMPLE_APP_NAME, execFileFn: deps.execFileFn, env: cliEnv,
         });
         // Persist the app id BEFORE the steps that can still fail. Without this a
         // failure anywhere below left no row at all, so the next boot ran bootstrap
@@ -690,11 +778,11 @@ export class LivewareSampleSupervisor {
             publicUrl: null, sampleVersion: version, status: "pending",
         });
         const publicUrl = await tunnelBind({
-            livewarePath, appId, port: server.port, execFileFn: deps.execFileFn,
+            livewarePath, appId, port: server.port, execFileFn: deps.execFileFn, env: cliEnv,
         });
         if (this.bailIfStopped())
             return;
-        const agent = await startTunnelAgent({ livewarePath, spawnFn: deps.spawnFn });
+        const agent = await startTunnelAgent({ livewarePath, spawnFn: deps.spawnFn, env: cliEnv });
         this.tunnelChild = agent.child;
         if (this.bailIfStopped())
             return;
@@ -749,8 +837,11 @@ export class LivewareSampleSupervisor {
         }
         if (this.bailIfStopped())
             return;
+        const cliEnv = await this.ensureCliEnv();
         const server = await startSampleServer({
-            appDir, port: row.port || DEFAULT_SAMPLE_PORT, spawnFn: deps.spawnFn,
+            appDir,
+            port: await resolveSamplePort(row.port || DEFAULT_SAMPLE_PORT, deps.probePortFn),
+            spawnFn: deps.spawnFn,
             agentUserId: deps.resolveAgentUserId?.() ?? null,
         });
         this.serverChild = server.child;
@@ -764,12 +855,14 @@ export class LivewareSampleSupervisor {
         // lifetime. `login` is idempotent; best-effort, so a stale token still falls
         // through to whatever credentials the CLI already has.
         const token = deps.resolveToken();
+        let loggedIn = false;
         if (token) {
             try {
-                await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn });
+                await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn, env: cliEnv });
+                loggedIn = true;
             }
             catch (err) {
-                deps.log?.warn?.(`liveware-sample: relaunch re-login failed; continuing with cached CLI credentials: ${String(err)}`);
+                deps.log?.warn?.(`liveware-sample: relaunch re-login failed; continuing only if the CLI has cached credentials: ${String(err)}`);
             }
             if (this.bailIfStopped())
                 return;
@@ -777,6 +870,20 @@ export class LivewareSampleSupervisor {
         else {
             deps.log?.debug?.("liveware-sample: no token; relaunch without re-login");
         }
+        // Falling through without a fresh login is only safe when the CLI actually
+        // has credentials cached. Since the private-HOME redirect those live in
+        // `<cliHome>/.clawling`, and a first relaunch after upgrading finds that
+        // home EMPTY — the old ones are still under the ambient `$HOME`. Continuing
+        // there makes every tunnelBind/agent call below fail auth, which surfaces as
+        // a confusing tunnel error rather than the credential problem it is, and
+        // burns the whole retry ladder on a state that cannot recover on its own.
+        // Throwing hands it to `startAttempt`'s ladder instead, so the worst case is
+        // a delayed sample rather than a silent auth failure.
+        if (!loggedIn && cliEnv && deps.cliHome) {
+            if (!(await hasCachedLivewareCredentials(deps.cliHome))) {
+                throw new Error(`liveware CLI has no cached credentials under ${deps.cliHome} and no token was available to log in`);
+            }
+        }
         // Kept after the re-login above so the lookup runs against a CLI that is
         // actually authenticated: a pending row's app id came straight from
         // `app create`'s parser and was never confirmed by the liveware side, so
@@ -786,6 +893,7 @@ export class LivewareSampleSupervisor {
         if (row.status === "pending") {
             const found = await livewareAppFindByName({
                 livewarePath, name: row.app_name, execFileFn: deps.execFileFn, log: deps.log,
+                env: cliEnv,
             });
             if (found && found !== appId) {
                 deps.log?.warn?.(`liveware-sample: pending app id ${appId} not listed; adopting ${found}`);
@@ -795,11 +903,11 @@ export class LivewareSampleSupervisor {
                 return;
         }
         const publicUrl = await tunnelBind({
-            livewarePath, appId, port: server.port, execFileFn: deps.execFileFn,
+            livewarePath, appId, port: server.port, execFileFn: deps.execFileFn, env: cliEnv,
         });
         if (this.bailIfStopped())
             return;
-        const agent = await startTunnelAgent({ livewarePath, spawnFn: deps.spawnFn });
+        const agent = await startTunnelAgent({ livewarePath, spawnFn: deps.spawnFn, env: cliEnv });
         this.tunnelChild = agent.child;
         if (this.bailIfStopped())
             return;

package/dist/src/runtime.js

@@ -7,7 +7,7 @@ import { createOpenclawClawlingApiClient } from "./api-client.js";
 import { buildActivationBootstrapText } from "./activation-greeting.js";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.js";
 import path from "node:path";
-import { ensureLivewareCli, resolveLivewarePath } from "./liveware-cli.js";
+import { ensureLivewareCli, livewareCliHomeDir, resolveLivewarePath } from "./liveware-cli.js";
 import { LivewareSampleSupervisor, } from "./liveware-sample.js";
 import { ClawlingApiError } from "./api-types.js";
 import { RefreshManager } from "./refresh-manager.js";
@@ -835,6 +835,9 @@ export async function startOpenclawClawlingGateway(params) {
             resolveToken: () => account.token ?? "",
             resolveAgentUserId: () => account.userId ?? null,
             resolveLivewarePath: () => resolveLivewarePath(stateDirForSample),
+            // Per-instance HOME for the liveware CLI: its credentials otherwise live
+            // in the host-global `$HOME/.clawling`, which a second profile clobbers.
+            cliHome: livewareCliHomeDir(stateDirForSample),
             cliReady: livewareCliReady,
             listApps: async () => {
                 const client = getConversationApiClient();

package/dist/src/skill-update.js

@@ -1,9 +1,9 @@
 import crypto from "node:crypto";
 import { existsSync, readdirSync } from "node:fs";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveStateDirFromEnv } from "./state-paths.js";
 /**
  * Conversational, adapter-driven skill hot-update for the OpenClaw ClawChat
  * plugin.
@@ -329,18 +329,14 @@ export async function managedSkillExists(managedDir, skillId) {
     }
 }
 /**
- * Resolve OpenClaw's state directory, mirroring the host `src/utils.ts:132-154`:
- * `OPENCLAW_STATE_DIR` if set; else the dirname of `OPENCLAW_CONFIG_PATH` if
- * set; else `~/.openclaw`.
+ * Resolve OpenClaw's state directory: `OPENCLAW_STATE_DIR` if set; else the
+ * dirname of `OPENCLAW_CONFIG_PATH` if set; else `<effective home>/.openclaw`,
+ * where the effective home honors `OPENCLAW_HOME`. Delegates to the shared
+ * mirror in `./state-paths.ts` — see there for why each rule matters under
+ * `openclaw --profile <name>`.
  */
 export function resolveStateDir(env = process.env) {
-    const stateDir = env.OPENCLAW_STATE_DIR?.trim();
-    if (stateDir)
-        return stateDir;
-    const configPath = env.OPENCLAW_CONFIG_PATH?.trim();
-    if (configPath)
-        return path.dirname(configPath);
-    return path.join(os.homedir(), ".openclaw");
+    return resolveStateDirFromEnv(env);
 }
 /**
  * Resolve the OpenClaw-managed skills directory — THE write target for an

package/dist/src/state-paths.js

@@ -0,0 +1,65 @@
+import os from "node:os";
+import path from "node:path";
+/**
+ * Local mirror of the OpenClaw host's state-directory resolution.
+ *
+ * WHY THIS EXISTS: most of the plugin resolves its state dir through the host
+ * (`openclaw/plugin-sdk/state-paths` or `runtime.state.resolveStateDir()`), and
+ * that is always the right answer. A few call sites cannot: the sqlite fallback
+ * in `storage.ts` runs when the SDK import/resolution throws, and
+ * `skill-update.ts` resolves the managed-skills dir without a `PluginRuntime`.
+ * Those sites used to guess `~/.openclaw` directly.
+ *
+ * That guess is wrong under `openclaw --profile <name>`, which isolates an
+ * instance by exporting `OPENCLAW_STATE_DIR=~/.openclaw-<name>` plus a matching
+ * `OPENCLAW_CONFIG_PATH` (host `src/cli/profile.ts:133-146`). A named profile
+ * that ignores those env vars silently lands on the DEFAULT profile's state dir
+ * — i.e. reads and writes the default profile's ClawChat database.
+ *
+ * It is also wrong about `OPENCLAW_HOME`: that variable replaces `$HOME` for
+ * every OpenClaw path default (host `src/infra/home-dir.ts:42-52`), it is NOT
+ * the state dir itself, so the correct default is `$OPENCLAW_HOME/.openclaw`.
+ *
+ * Mirrors host `src/config/state-dir.ts:28-38` + `src/infra/home-dir.ts:42-52`.
+ * Deliberately NOT mirrored: the legacy `~/.clawdbot` fallback (host
+ * `src/config/state-dir.ts:41-67`). This is a last-resort path; probing for a
+ * legacy directory here would be more surprising than landing on `~/.openclaw`.
+ */
+const STATE_DIRNAME = ".openclaw";
+function trimmed(value) {
+    const text = value?.trim();
+    return text ? text : undefined;
+}
+/** Expand a leading `~` against the OS home, matching the host's behavior. */
+function expandTilde(value, osHome) {
+    if (value !== "~" && !value.startsWith("~/") && !value.startsWith("~\\"))
+        return value;
+    if (!osHome)
+        return value;
+    return path.join(osHome, value.slice(1));
+}
+/**
+ * The home OpenClaw derives its defaults from: `OPENCLAW_HOME` wins, else the
+ * ordinary OS home (`HOME`, then `USERPROFILE`, then `os.homedir()`).
+ */
+export function resolveEffectiveHomeDir(env = process.env, homedir = os.homedir) {
+    const osHome = trimmed(env.HOME) ?? trimmed(env.USERPROFILE) ?? trimmed(homedir());
+    const explicit = trimmed(env.OPENCLAW_HOME);
+    if (explicit)
+        return expandTilde(explicit, osHome);
+    return osHome ?? homedir();
+}
+/**
+ * Resolve the state dir the way the host would, from env alone:
+ * `OPENCLAW_STATE_DIR`, else the dirname of `OPENCLAW_CONFIG_PATH`, else
+ * `<effective home>/.openclaw`.
+ */
+export function resolveStateDirFromEnv(env = process.env, homedir = os.homedir) {
+    const stateDir = trimmed(env.OPENCLAW_STATE_DIR);
+    if (stateDir)
+        return expandTilde(stateDir, resolveEffectiveHomeDir(env, homedir));
+    const configPath = trimmed(env.OPENCLAW_CONFIG_PATH);
+    if (configPath)
+        return path.dirname(expandTilde(configPath, resolveEffectiveHomeDir(env, homedir)));
+    return path.join(resolveEffectiveHomeDir(env, homedir), STATE_DIRNAME);
+}

package/dist/src/storage.js

@@ -1,8 +1,8 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
+import { resolveStateDirFromEnv } from "./state-paths.js";
 const DB_FILENAME = "clawchat.sqlite";
 const DEFAULT_BOOTSTRAP_CLAIM_STALE_MS = 5 * 60 * 1000;
 const MIGRATIONS = [
@@ -187,9 +187,14 @@ CREATE TABLE IF NOT EXISTS recalled_messages (
 `,
     },
 ];
+/**
+ * Only reached when the host SDK's `resolveStateDir()` throws. It must still
+ * honor `OPENCLAW_STATE_DIR` / `OPENCLAW_CONFIG_PATH`: guessing `~/.openclaw`
+ * here would point a named `--profile` instance at the DEFAULT profile's
+ * database. See `./state-paths.ts` for the full mirror + rationale.
+ */
 function fallbackDbPath() {
-    const home = process.env.OPENCLAW_HOME || path.join(os.homedir(), ".openclaw");
-    return path.join(home, DB_FILENAME);
+    return clawChatDbPathForStateDir(resolveStateDirFromEnv());
 }
 export function clawChatDbPathForStateDir(stateDir) {
     return path.join(stateDir, DB_FILENAME);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.9.8-2",
+  "version": "2026.9.10-1",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/client.ts

@@ -3,6 +3,7 @@ import os from "node:os";
 import type { Envelope, Transport } from "./protocol-types.ts";
 import { createClawChatClient, type ClawlingChatClient } from "./ws-client.ts";
 import { CHANNEL_ID, type ResolvedOpenclawClawlingAccount } from "./config.ts";
+import { resolveStateDirFromEnv } from "./state-paths.ts";
 
 export type { ChatType } from "./protocol-types.ts";
 
@@ -26,8 +27,32 @@ export interface CreateClientOverrides {
   };
 }
 
-export function resolveOpenclawClawlingDeviceId(account: ResolvedOpenclawClawlingAccount): string {
-  const material = [CHANNEL_ID, account.accountId, account.userId, os.hostname()].join("\0");
+/**
+ * Derive this instance's `device_id` from stable, per-instance material.
+ *
+ * The state dir is part of the material because it is the ONLY input that
+ * distinguishes two OpenClaw instances on one host: `openclaw --profile <name>`
+ * isolates an instance by pointing it at `~/.openclaw-<name>` (host
+ * `src/cli/profile.ts:133-146`), but `accountId` is a constant and `hostname()`
+ * is shared. Two profiles that end up on the SAME ClawChat identity — trivially
+ * easy, since an exported `CLAWCHAT_TOKEN` is inherited by a second profile
+ * whose own channel config is still empty (`config.ts` env fallbacks) — would
+ * otherwise present a byte-identical device id and evict each other forever
+ * (`ws-client.ts` close codes 4001/4002 and the escalating takeover floor).
+ *
+ * Existing installs are unaffected: once the server has resolved a device id it
+ * is persisted and replayed as `deviceIdOverride` (`runtime.ts`
+ * `getLastResolvedDeviceId` → `markConnectionReady`), so this derivation only
+ * governs a first-ever connect.
+ */
+export function resolveOpenclawClawlingDeviceId(
+  account: ResolvedOpenclawClawlingAccount,
+  opts: { stateDir?: string | null } = {},
+): string {
+  const stateDir = opts.stateDir?.trim() || resolveStateDirFromEnv();
+  const material = [CHANNEL_ID, account.accountId, account.userId, os.hostname(), stateDir].join(
+    "\0",
+  );
   const digest = createHash("sha256").update(material).digest("hex").slice(0, 24);
   return `${CHANNEL_ID}-${digest}`;
 }

package/src/liveware-cli.ts

@@ -20,6 +20,38 @@ export function livewareDir(stateDir?: string): string {
   return path.join(root, "clawchat", "liveware");
 }
 
+/**
+ * Private HOME for the liveware CLI: `<stateDir>/clawchat/liveware-home`.
+ *
+ * The CLI keeps its login credentials in `$HOME/.clawling`, which is
+ * host-global. Two OpenClaw instances on one box (`openclaw --profile <name>`,
+ * each with its own state dir but the same OS account) each run
+ * `liveware login --access-token <their own>`, so the last writer wins and the
+ * earlier instance's long-lived `liveware agent` daemon ends up authenticated
+ * as the OTHER account's user. Pointing HOME at the state dir makes the
+ * credential store per-instance, which is the same isolation the rest of the
+ * plugin already gets for free.
+ *
+ * Migration is automatic: `livewareLogin` runs on every bootstrap AND (best
+ * effort) on every relaunch, so an existing install simply re-logs into its new
+ * private home on the next start.
+ */
+export function livewareCliHomeDir(stateDir?: string): string {
+  const root = stateDir ?? resolveStateDir();
+  return path.join(root, "clawchat", "liveware-home");
+}
+
+/**
+ * Environment for every liveware CLI invocation: the ambient env with HOME
+ * (and Windows' USERPROFILE) redirected to {@link livewareCliHomeDir}.
+ */
+export function livewareCliEnv(
+  cliHome: string,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  return { ...baseEnv, HOME: cliHome, USERPROFILE: cliHome };
+}
+
 /** Local filename for the downloaded binary; Windows needs a .exe suffix. */
 export function livewareBinaryName(plat: string = process.platform): string {
   return plat === "win32" ? "liveware.exe" : "liveware";

package/src/liveware-sample.ts

@@ -7,10 +7,11 @@
 import crypto from "node:crypto";
 import { execFile as nodeExecFile, spawn as nodeSpawn, type ChildProcess } from "node:child_process";
 import fs from "node:fs";
+import net from "node:net";
 import path from "node:path";
 import { DEFAULT_SKILLS_REF, OFFICIAL_SKILLS_BASE, type FetchLike } from "./skill-update.ts";
 import type { LivewareSampleRow, LivewareSampleUpsert } from "./storage.ts";
-import type { LivewareLogger } from "./liveware-cli.ts";
+import { livewareCliEnv, type LivewareLogger } from "./liveware-cli.ts";
 
 export const LIVEWARES_TARGET = "openclaw";
 export const LIVEWARE_SAMPLE_ID = "liveware-sample";
@@ -303,6 +304,55 @@ function waitForOutput(
   });
 }
 
+/**
+ * Probe one loopback port: resolves to the bound port when free, else null.
+ * Port `0` asks the kernel for any free ephemeral port and reports which.
+ */
+export type ProbePortLike = (port: number) => Promise<number | null>;
+
+const probeLoopbackPort: ProbePortLike = (port) =>
+  new Promise((resolve) => {
+    const srv = net.createServer();
+    srv.once("error", () => resolve(null));
+    srv.listen({ port, host: "127.0.0.1", exclusive: true }, () => {
+      const addr = srv.address();
+      const bound = addr && typeof addr === "object" ? addr.port : null;
+      srv.close(() => resolve(bound));
+    });
+  });
+
+/**
+ * Choose the port the sample server should bind.
+ *
+ * `DEFAULT_SAMPLE_PORT` used to be passed to the child unconditionally, so a
+ * second OpenClaw instance on the same host (`openclaw --profile <name>`) lost
+ * the bind race, never printed its `{"port"…}` line, and burnt the whole
+ * `START_RETRY_DELAYS_MS` ladder before going dormant — permanently, because
+ * the port persisted in BOTH state dirs was the same constant.
+ *
+ * `preferred` is still tried first so a single-instance install keeps its
+ * familiar port and its existing tunnel binding; anything else falls back to a
+ * kernel-assigned ephemeral port. A changed port costs nothing: bootstrap and
+ * relaunch both re-run `tunnel bind` with the actual port and only re-register
+ * with ClawChat when the resulting public URL changed.
+ *
+ * The probe closes its socket before the child binds, so there is a small race
+ * with an unrelated process. That is inherent to pre-allocating a port for a
+ * child, and a lost race is a transient start failure the retry ladder handles.
+ */
+export async function resolveSamplePort(
+  preferred: number | null | undefined,
+  probeFn: ProbePortLike = probeLoopbackPort,
+): Promise<number> {
+  if (typeof preferred === "number" && preferred > 0) {
+    const kept = await probeFn(preferred);
+    if (kept) return kept;
+  }
+  const ephemeral = await probeFn(0);
+  if (!ephemeral) throw new Error("liveware-sample: cannot allocate a local port");
+  return ephemeral;
+}
+
 export async function startSampleServer(opts: {
   appDir: string;
   port: number;
@@ -357,13 +407,14 @@ export async function tunnelBind(opts: {
   appId: string;
   port: number;
   execFileFn?: ExecFileLike;
+  env?: NodeJS.ProcessEnv;
 }): Promise<string> {
   const execFileFn = opts.execFileFn ?? nodeExecFile;
   const output = await new Promise<string>((resolve, reject) => {
     execFileFn(
       opts.livewarePath,
       ["tunnel", "bind", opts.appId, `http://127.0.0.1:${opts.port}`],
-      { timeout: CLI_TIMEOUT_MS },
+      { timeout: CLI_TIMEOUT_MS, ...(opts.env ? { env: opts.env } : {}) },
       (err, out, errOut) => {
         if (err) { reject(new Error(`liveware tunnel bind failed: ${errOut || out || String(err)}`.trim())); return; }
         resolve(`${String(out ?? "")}\n${String(errOut ?? "")}`);
@@ -399,12 +450,13 @@ export async function startTunnelAgent(opts: {
   livewarePath: string;
   spawnFn?: SpawnLike;
   timeoutMs?: number;
+  env?: NodeJS.ProcessEnv;
 }): Promise<{ child: ChildProcess }> {
   const spawnFn = opts.spawnFn ?? nodeSpawn;
   const child = spawnFn(
     opts.livewarePath,
     ["agent"],
-    { stdio: ["ignore", "pipe", "pipe"] },
+    { stdio: ["ignore", "pipe", "pipe"], ...(opts.env ? { env: opts.env } : {}) },
   );
   await waitForOutput(
     child,
@@ -415,17 +467,40 @@ export async function startTunnelAgent(opts: {
   return { child };
 }
 
+/** Where the liveware CLI keeps its login state, relative to its `HOME`. */
+const LIVEWARE_CREDENTIAL_DIRNAME = ".clawling";
+
+/**
+ * True when the liveware CLI has usable cached credentials under `cliHome`.
+ *
+ * Tolerates either shape the CLI might use: a credential file (non-empty) or a
+ * directory (non-empty). Anything unreadable answers "no" — the caller's only
+ * use is deciding whether it is safe to skip a login, and guessing "yes" there
+ * is exactly the failure this check exists to prevent.
+ */
+export async function hasCachedLivewareCredentials(cliHome: string): Promise<boolean> {
+  const target = path.join(cliHome, LIVEWARE_CREDENTIAL_DIRNAME);
+  try {
+    const stat = await fs.promises.stat(target);
+    if (stat.isDirectory()) return (await fs.promises.readdir(target)).length > 0;
+    return stat.size > 0;
+  } catch {
+    return false;
+  }
+}
+
 export async function livewareLogin(opts: {
   livewarePath: string;
   token: string;
   execFileFn?: ExecFileLike;
+  env?: NodeJS.ProcessEnv;
 }): Promise<void> {
   const execFileFn = opts.execFileFn ?? nodeExecFile;
   await new Promise<void>((resolve, reject) => {
     execFileFn(
       opts.livewarePath,
       ["login", "--access-token", opts.token],
-      { timeout: CLI_TIMEOUT_MS },
+      { timeout: CLI_TIMEOUT_MS, ...(opts.env ? { env: opts.env } : {}) },
       (err, stdout, stderr) => {
         if (!err) { resolve(); return; }
         const scrub = (s: string) => (opts.token ? String(s).split(opts.token).join("***") : String(s));
@@ -544,13 +619,14 @@ export async function livewareAppFindByName(opts: {
   name: string;
   execFileFn?: ExecFileLike;
   log?: LivewareLogger;
+  env?: NodeJS.ProcessEnv;
 }): Promise<string | null> {
   const execFileFn = opts.execFileFn ?? nodeExecFile;
   const stdout = await new Promise<string | null>((resolve) => {
     execFileFn(
       opts.livewarePath,
       ["app", "list"],
-      { timeout: CLI_TIMEOUT_MS },
+      { timeout: CLI_TIMEOUT_MS, ...(opts.env ? { env: opts.env } : {}) },
       (err, out, errOut) => {
         if (err) {
           opts.log?.debug?.(
@@ -570,13 +646,14 @@ export async function livewareAppCreate(opts: {
   livewarePath: string;
   name: string;
   execFileFn?: ExecFileLike;
+  env?: NodeJS.ProcessEnv;
 }): Promise<string> {
   const execFileFn = opts.execFileFn ?? nodeExecFile;
   const stdout = await new Promise<string>((resolve, reject) => {
     execFileFn(
       opts.livewarePath,
       ["app", "create", opts.name],
-      { timeout: CLI_TIMEOUT_MS },
+      { timeout: CLI_TIMEOUT_MS, ...(opts.env ? { env: opts.env } : {}) },
       (err, out, errOut) => {
         if (err) { reject(new Error(`liveware app create failed: ${errOut || out || String(err)}`.trim())); return; }
         resolve(String(out ?? ""));
@@ -623,6 +700,11 @@ export type LivewareSampleSupervisorDeps = {
   ref?: string;
   spawnFn?: SpawnLike;
   execFileFn?: ExecFileLike;
+  /** Private HOME for the liveware CLI (`livewareCliHomeDir(stateDir)`), so two
+   * instances on one host do not share `$HOME/.clawling`. Absent → the CLI
+   * inherits the ambient HOME, which is the pre-isolation behavior. */
+  cliHome?: string;
+  probePortFn?: ProbePortLike;
   log?: LivewareLogger;
   setTimeoutFn?: typeof setTimeout;
 };
@@ -769,6 +851,28 @@ export class LivewareSampleSupervisor {
     return true;
   }
 
+  /**
+   * Environment for every liveware CLI invocation in this flow. Creates the
+   * private HOME first: the CLI writes `<HOME>/.clawling` on login and a
+   * missing parent would fail the very step that isolates the credentials.
+   * Falls back to the ambient env when the dir cannot be created, so an
+   * unwritable state dir degrades to the old shared-HOME behavior instead of
+   * breaking the sample outright.
+   */
+  private async ensureCliEnv(): Promise<NodeJS.ProcessEnv | undefined> {
+    const cliHome = this.deps.cliHome?.trim();
+    if (!cliHome) return undefined;
+    try {
+      await fs.promises.mkdir(cliHome, { recursive: true });
+    } catch (err) {
+      this.deps.log?.warn?.(
+        `liveware-sample: cannot create private CLI home ${cliHome}; using ambient HOME: ${String(err)}`,
+      );
+      return undefined;
+    }
+    return livewareCliEnv(cliHome);
+  }
+
   private async bootstrap(): Promise<void> {
     const { deps } = this;
     if (this.stopped) return;
@@ -792,13 +896,16 @@ export class LivewareSampleSupervisor {
       fetchFn: deps.fetchFn, sampleRoot: deps.sampleRoot, ref: deps.ref,
     });
     if (this.bailIfStopped()) return;
+    const cliEnv = await this.ensureCliEnv();
     const server = await startSampleServer({
-      appDir, port: DEFAULT_SAMPLE_PORT, spawnFn: deps.spawnFn,
+      appDir,
+      port: await resolveSamplePort(DEFAULT_SAMPLE_PORT, deps.probePortFn),
+      spawnFn: deps.spawnFn,
       agentUserId: deps.resolveAgentUserId?.() ?? null,
     });
     this.serverChild = server.child;
     if (this.bailIfStopped()) return;
-    await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn });
+    await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn, env: cliEnv });
     // Reuse an app we already own before minting another one. `app create` is not
     // idempotent and nothing here ever reconciled against the liveware side, so
     // every bootstrap that died past this point (no row was written until the very
@@ -806,13 +913,14 @@ export class LivewareSampleSupervisor {
     // app quota. Best-effort: an unreadable list falls through to `app create`.
     const existingAppId = await livewareAppFindByName({
       livewarePath, name: LIVEWARE_SAMPLE_APP_NAME, execFileFn: deps.execFileFn, log: deps.log,
+      env: cliEnv,
     });
     if (this.bailIfStopped()) return;
     if (existingAppId) {
       deps.log?.debug?.(`liveware-sample: reusing existing liveware app ${existingAppId}`);
     }
     const appId = existingAppId ?? await livewareAppCreate({
-      livewarePath, name: LIVEWARE_SAMPLE_APP_NAME, execFileFn: deps.execFileFn,
+      livewarePath, name: LIVEWARE_SAMPLE_APP_NAME, execFileFn: deps.execFileFn, env: cliEnv,
     });
     // Persist the app id BEFORE the steps that can still fail. Without this a
     // failure anywhere below left no row at all, so the next boot ran bootstrap
@@ -824,10 +932,10 @@ export class LivewareSampleSupervisor {
       publicUrl: null, sampleVersion: version, status: "pending",
     });
     const publicUrl = await tunnelBind({
-      livewarePath, appId, port: server.port, execFileFn: deps.execFileFn,
+      livewarePath, appId, port: server.port, execFileFn: deps.execFileFn, env: cliEnv,
     });
     if (this.bailIfStopped()) return;
-    const agent = await startTunnelAgent({ livewarePath, spawnFn: deps.spawnFn });
+    const agent = await startTunnelAgent({ livewarePath, spawnFn: deps.spawnFn, env: cliEnv });
     this.tunnelChild = agent.child;
     if (this.bailIfStopped()) return;
     await deps.registerApp({ name: LIVEWARE_SAMPLE_APP_NAME, appId, url: publicUrl });
@@ -877,8 +985,11 @@ export class LivewareSampleSupervisor {
       deps.log?.debug?.(`liveware-sample: download failed, reusing local copy: ${String(err)}`);
     }
     if (this.bailIfStopped()) return;
+    const cliEnv = await this.ensureCliEnv();
     const server = await startSampleServer({
-      appDir, port: row.port || DEFAULT_SAMPLE_PORT, spawnFn: deps.spawnFn,
+      appDir,
+      port: await resolveSamplePort(row.port || DEFAULT_SAMPLE_PORT, deps.probePortFn),
+      spawnFn: deps.spawnFn,
       agentUserId: deps.resolveAgentUserId?.() ?? null,
     });
     this.serverChild = server.child;
@@ -891,18 +1002,36 @@ export class LivewareSampleSupervisor {
     // lifetime. `login` is idempotent; best-effort, so a stale token still falls
     // through to whatever credentials the CLI already has.
     const token = deps.resolveToken();
+    let loggedIn = false;
     if (token) {
       try {
-        await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn });
+        await livewareLogin({ livewarePath, token, execFileFn: deps.execFileFn, env: cliEnv });
+        loggedIn = true;
       } catch (err) {
         deps.log?.warn?.(
-          `liveware-sample: relaunch re-login failed; continuing with cached CLI credentials: ${String(err)}`,
+          `liveware-sample: relaunch re-login failed; continuing only if the CLI has cached credentials: ${String(err)}`,
         );
       }
       if (this.bailIfStopped()) return;
     } else {
       deps.log?.debug?.("liveware-sample: no token; relaunch without re-login");
     }
+    // Falling through without a fresh login is only safe when the CLI actually
+    // has credentials cached. Since the private-HOME redirect those live in
+    // `<cliHome>/.clawling`, and a first relaunch after upgrading finds that
+    // home EMPTY — the old ones are still under the ambient `$HOME`. Continuing
+    // there makes every tunnelBind/agent call below fail auth, which surfaces as
+    // a confusing tunnel error rather than the credential problem it is, and
+    // burns the whole retry ladder on a state that cannot recover on its own.
+    // Throwing hands it to `startAttempt`'s ladder instead, so the worst case is
+    // a delayed sample rather than a silent auth failure.
+    if (!loggedIn && cliEnv && deps.cliHome) {
+      if (!(await hasCachedLivewareCredentials(deps.cliHome))) {
+        throw new Error(
+          `liveware CLI has no cached credentials under ${deps.cliHome} and no token was available to log in`,
+        );
+      }
+    }
     // Kept after the re-login above so the lookup runs against a CLI that is
     // actually authenticated: a pending row's app id came straight from
     // `app create`'s parser and was never confirmed by the liveware side, so
@@ -912,6 +1041,7 @@ export class LivewareSampleSupervisor {
     if (row.status === "pending") {
       const found = await livewareAppFindByName({
         livewarePath, name: row.app_name, execFileFn: deps.execFileFn, log: deps.log,
+        env: cliEnv,
       });
       if (found && found !== appId) {
         deps.log?.warn?.(`liveware-sample: pending app id ${appId} not listed; adopting ${found}`);
@@ -920,10 +1050,10 @@ export class LivewareSampleSupervisor {
       if (this.bailIfStopped()) return;
     }
     const publicUrl = await tunnelBind({
-      livewarePath, appId, port: server.port, execFileFn: deps.execFileFn,
+      livewarePath, appId, port: server.port, execFileFn: deps.execFileFn, env: cliEnv,
     });
     if (this.bailIfStopped()) return;
-    const agent = await startTunnelAgent({ livewarePath, spawnFn: deps.spawnFn });
+    const agent = await startTunnelAgent({ livewarePath, spawnFn: deps.spawnFn, env: cliEnv });
     this.tunnelChild = agent.child;
     if (this.bailIfStopped()) return;
     // A pending row has never been registered with ClawChat (public_url is null),

package/src/runtime.ts

@@ -19,7 +19,7 @@ import { createOpenclawClawlingApiClient } from "./api-client.ts";
 import { buildActivationBootstrapText } from "./activation-greeting.ts";
 import { reportPluginVersionSafe, resolvePluginVersion } from "./plugin-report.ts";
 import path from "node:path";
-import { ensureLivewareCli, resolveLivewarePath } from "./liveware-cli.ts";
+import { ensureLivewareCli, livewareCliHomeDir, resolveLivewarePath } from "./liveware-cli.ts";
 import {
   LivewareSampleSupervisor,
   type LivewareSampleStoreLike,
@@ -1162,6 +1162,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       resolveToken: () => account.token ?? "",
       resolveAgentUserId: () => account.userId ?? null,
       resolveLivewarePath: () => resolveLivewarePath(stateDirForSample),
+      // Per-instance HOME for the liveware CLI: its credentials otherwise live
+      // in the host-global `$HOME/.clawling`, which a second profile clobbers.
+      cliHome: livewareCliHomeDir(stateDirForSample),
       cliReady: livewareCliReady,
       listApps: async () => {
         const client = getConversationApiClient();

package/src/skill-update.ts

@@ -1,9 +1,9 @@
 import crypto from "node:crypto";
 import { existsSync, readdirSync } from "node:fs";
 import fs from "node:fs/promises";
-import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { resolveStateDirFromEnv } from "./state-paths.ts";
 
 /**
  * Conversational, adapter-driven skill hot-update for the OpenClaw ClawChat
@@ -433,16 +433,14 @@ export async function managedSkillExists(managedDir: string, skillId: string): P
 }
 
 /**
- * Resolve OpenClaw's state directory, mirroring the host `src/utils.ts:132-154`:
- * `OPENCLAW_STATE_DIR` if set; else the dirname of `OPENCLAW_CONFIG_PATH` if
- * set; else `~/.openclaw`.
+ * Resolve OpenClaw's state directory: `OPENCLAW_STATE_DIR` if set; else the
+ * dirname of `OPENCLAW_CONFIG_PATH` if set; else `<effective home>/.openclaw`,
+ * where the effective home honors `OPENCLAW_HOME`. Delegates to the shared
+ * mirror in `./state-paths.ts` — see there for why each rule matters under
+ * `openclaw --profile <name>`.
  */
 export function resolveStateDir(env: NodeJS.ProcessEnv = process.env): string {
-  const stateDir = env.OPENCLAW_STATE_DIR?.trim();
-  if (stateDir) return stateDir;
-  const configPath = env.OPENCLAW_CONFIG_PATH?.trim();
-  if (configPath) return path.dirname(configPath);
-  return path.join(os.homedir(), ".openclaw");
+  return resolveStateDirFromEnv(env);
 }
 
 /**

package/src/state-paths.ts

@@ -0,0 +1,72 @@
+import os from "node:os";
+import path from "node:path";
+
+/**
+ * Local mirror of the OpenClaw host's state-directory resolution.
+ *
+ * WHY THIS EXISTS: most of the plugin resolves its state dir through the host
+ * (`openclaw/plugin-sdk/state-paths` or `runtime.state.resolveStateDir()`), and
+ * that is always the right answer. A few call sites cannot: the sqlite fallback
+ * in `storage.ts` runs when the SDK import/resolution throws, and
+ * `skill-update.ts` resolves the managed-skills dir without a `PluginRuntime`.
+ * Those sites used to guess `~/.openclaw` directly.
+ *
+ * That guess is wrong under `openclaw --profile <name>`, which isolates an
+ * instance by exporting `OPENCLAW_STATE_DIR=~/.openclaw-<name>` plus a matching
+ * `OPENCLAW_CONFIG_PATH` (host `src/cli/profile.ts:133-146`). A named profile
+ * that ignores those env vars silently lands on the DEFAULT profile's state dir
+ * — i.e. reads and writes the default profile's ClawChat database.
+ *
+ * It is also wrong about `OPENCLAW_HOME`: that variable replaces `$HOME` for
+ * every OpenClaw path default (host `src/infra/home-dir.ts:42-52`), it is NOT
+ * the state dir itself, so the correct default is `$OPENCLAW_HOME/.openclaw`.
+ *
+ * Mirrors host `src/config/state-dir.ts:28-38` + `src/infra/home-dir.ts:42-52`.
+ * Deliberately NOT mirrored: the legacy `~/.clawdbot` fallback (host
+ * `src/config/state-dir.ts:41-67`). This is a last-resort path; probing for a
+ * legacy directory here would be more surprising than landing on `~/.openclaw`.
+ */
+
+const STATE_DIRNAME = ".openclaw";
+
+function trimmed(value: string | undefined): string | undefined {
+  const text = value?.trim();
+  return text ? text : undefined;
+}
+
+/** Expand a leading `~` against the OS home, matching the host's behavior. */
+function expandTilde(value: string, osHome: string | undefined): string {
+  if (value !== "~" && !value.startsWith("~/") && !value.startsWith("~\\")) return value;
+  if (!osHome) return value;
+  return path.join(osHome, value.slice(1));
+}
+
+/**
+ * The home OpenClaw derives its defaults from: `OPENCLAW_HOME` wins, else the
+ * ordinary OS home (`HOME`, then `USERPROFILE`, then `os.homedir()`).
+ */
+export function resolveEffectiveHomeDir(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const osHome = trimmed(env.HOME) ?? trimmed(env.USERPROFILE) ?? trimmed(homedir());
+  const explicit = trimmed(env.OPENCLAW_HOME);
+  if (explicit) return expandTilde(explicit, osHome);
+  return osHome ?? homedir();
+}
+
+/**
+ * Resolve the state dir the way the host would, from env alone:
+ * `OPENCLAW_STATE_DIR`, else the dirname of `OPENCLAW_CONFIG_PATH`, else
+ * `<effective home>/.openclaw`.
+ */
+export function resolveStateDirFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  const stateDir = trimmed(env.OPENCLAW_STATE_DIR);
+  if (stateDir) return expandTilde(stateDir, resolveEffectiveHomeDir(env, homedir));
+  const configPath = trimmed(env.OPENCLAW_CONFIG_PATH);
+  if (configPath) return path.dirname(expandTilde(configPath, resolveEffectiveHomeDir(env, homedir)));
+  return path.join(resolveEffectiveHomeDir(env, homedir), STATE_DIRNAME);
+}

package/src/storage.ts

@@ -1,8 +1,8 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import { DatabaseSync } from "node:sqlite";
 import { resolveStateDir } from "openclaw/plugin-sdk/state-paths";
+import { resolveStateDirFromEnv } from "./state-paths.ts";
 
 type Log = { error?: (message: string) => void };
 
@@ -406,9 +406,14 @@ CREATE TABLE IF NOT EXISTS recalled_messages (
   },
 ];
 
+/**
+ * Only reached when the host SDK's `resolveStateDir()` throws. It must still
+ * honor `OPENCLAW_STATE_DIR` / `OPENCLAW_CONFIG_PATH`: guessing `~/.openclaw`
+ * here would point a named `--profile` instance at the DEFAULT profile's
+ * database. See `./state-paths.ts` for the full mirror + rationale.
+ */
 function fallbackDbPath(): string {
-  const home = process.env.OPENCLAW_HOME || path.join(os.homedir(), ".openclaw");
-  return path.join(home, DB_FILENAME);
+  return clawChatDbPathForStateDir(resolveStateDirFromEnv());
 }
 
 export function clawChatDbPathForStateDir(stateDir: string): string {