fix(paths): respect OPENCLAW_HOME for all internal path resolution (#12091)

* fix(paths): respect OPENCLAW_HOME for all internal path resolution (#11995)

Add home-dir module (src/infra/home-dir.ts) that centralizes home
directory resolution with precedence: OPENCLAW_HOME > HOME > USERPROFILE > os.homedir().

Migrate all path-sensitive callsites: config IO, agent dirs, session
transcripts, pairing store, cron store, doctor, CLI profiles.

Add envHomedir() helper in config/paths.ts to reduce lambda noise.
Document OPENCLAW_HOME in docs/help/environment.md.

* fix(paths): handle OPENCLAW_HOME '~' fallback (#12091) (thanks @sebslight)

* docs: mention OPENCLAW_HOME in install and getting started (#12091) (thanks @sebslight)

* fix(status): show OPENCLAW_HOME in shortened paths (#12091) (thanks @sebslight)

* docs(changelog): clarify OPENCLAW_HOME and HOME precedence (#12091) (thanks @sebslight)

CHANGELOG.md

@@ -16,6 +16,7 @@ Docs: https://docs.openclaw.ai
 
 - Exec approvals: format forwarded command text as inline/fenced monospace for safer approval scanning across channels. (#11937)
 - Docs: fix language switcher ordering and Japanese locale flag in Mintlify nav. (#12023) Thanks @joshp123.
+- Paths: add `OPENCLAW_HOME` and make internal path resolution respect `HOME`/`USERPROFILE` before `os.homedir()` across config, agents, sessions, pairing, cron, and CLI profiles. (#12091) Thanks @sebslight.
 - Thinking: allow xhigh for `github-copilot/gpt-5.2-codex` and `github-copilot/gpt-5.2`. (#11646) Thanks @seans-openclawbot.
 - Discord: support forum/media `thread create` starter messages, wire `message thread create --message`, and harden thread-create routing. (#10062) Thanks @jarvis89757.
 - Gateway: stabilize chat routing by canonicalizing node session keys for node-originated chat methods. (#11755) Thanks @mbelinky.

docs/help/environment.md

@@ -74,6 +74,32 @@ You can reference env vars directly in config string values using `${VAR_NAME}`
 
 See [Configuration: Env var substitution](/gateway/configuration#env-var-substitution-in-config) for full details.
 
+## Path-related env vars
+
+| Variable               | Purpose                                                                                                                                                                          |
+| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENCLAW_HOME`        | Override the home directory used for all internal path resolution (`~/.openclaw/`, agent dirs, sessions, credentials). Useful when running OpenClaw as a dedicated service user. |
+| `OPENCLAW_STATE_DIR`   | Override the state directory (default `~/.openclaw`).                                                                                                                            |
+| `OPENCLAW_CONFIG_PATH` | Override the config file path (default `~/.openclaw/openclaw.json`).                                                                                                             |
+
+### `OPENCLAW_HOME`
+
+When set, `OPENCLAW_HOME` replaces the system home directory (`$HOME` / `os.homedir()`) for all internal path resolution. This enables full filesystem isolation for headless service accounts.
+
+**Precedence:** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > `os.homedir()`
+
+**Example** (macOS LaunchDaemon):
+
+```xml
+<key>EnvironmentVariables</key>
+<dict>
+  <key>OPENCLAW_HOME</key>
+  <string>/Users/kira</string>
+</dict>
+```
+
+`OPENCLAW_HOME` can also be set to a tilde path (e.g. `~/svc`), which gets expanded using `$HOME` before use.
+
 ## Related
 
 - [Gateway configuration](/gateway/configuration)

docs/install/index.md

@@ -163,6 +163,14 @@ openclaw status         # gateway status
 openclaw dashboard      # open the browser UI
 ```
 
+If you need custom runtime paths, use:
+
+- `OPENCLAW_HOME` for home-directory based internal paths
+- `OPENCLAW_STATE_DIR` for mutable state location
+- `OPENCLAW_CONFIG_PATH` for config file location
+
+See [Environment vars](/help/environment) for precedence and full details.
+
 ## Troubleshooting: `openclaw` not found
 
 <Accordion title="PATH diagnosis and fix">

docs/install/nix.md

@@ -64,7 +64,9 @@ defaults write bot.molt.mac openclaw.nixMode -bool true
 ### Config + state paths
 
 OpenClaw reads JSON5 config from `OPENCLAW_CONFIG_PATH` and stores mutable data in `OPENCLAW_STATE_DIR`.
+When needed, you can also set `OPENCLAW_HOME` to control the base home directory used for internal path resolution.
 
+- `OPENCLAW_HOME` (default precedence: `HOME` / `USERPROFILE` / `os.homedir()`)
 - `OPENCLAW_STATE_DIR` (default: `~/.openclaw`)
 - `OPENCLAW_CONFIG_PATH` (default: `$OPENCLAW_STATE_DIR/openclaw.json`)
 

docs/start/getting-started.md

@@ -96,6 +96,16 @@ If the Control UI loads, your Gateway is ready for use.
   </Accordion>
 </AccordionGroup>
 
+## Useful environment variables
+
+If you run OpenClaw as a service account or want custom config/state locations:
+
+- `OPENCLAW_HOME` sets the home directory used for internal path resolution.
+- `OPENCLAW_STATE_DIR` overrides the state directory.
+- `OPENCLAW_CONFIG_PATH` overrides the config file path.
+
+Full environment variable reference: [Environment vars](/help/environment).
+
 ## Go deeper
 
 <Columns>

src/agents/agent-scope.test.ts

@@ -1,11 +1,17 @@
-import { describe, expect, it } from "vitest";
+import { afterEach, describe, expect, it, vi } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import {
   resolveAgentConfig,
+  resolveAgentDir,
   resolveAgentModelFallbacksOverride,
   resolveAgentModelPrimary,
+  resolveAgentWorkspaceDir,
 } from "./agent-scope.js";
 
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
 describe("resolveAgentConfig", () => {
   it("should return undefined when no agents config exists", () => {
     const cfg: OpenClawConfig = {};
@@ -200,4 +206,18 @@ describe("resolveAgentConfig", () => {
     expect(result).toBeDefined();
     expect(result?.workspace).toBe("~/openclaw");
   });
+
+  it("uses OPENCLAW_HOME for default agent workspace", () => {
+    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
+
+    const workspace = resolveAgentWorkspaceDir({} as OpenClawConfig, "main");
+    expect(workspace).toBe("/srv/openclaw-home/.openclaw/workspace");
+  });
+
+  it("uses OPENCLAW_HOME for default agentDir", () => {
+    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
+
+    const agentDir = resolveAgentDir({} as OpenClawConfig, "main");
+    expect(agentDir).toBe("/srv/openclaw-home/.openclaw/agents/main/agent");
+  });
 });

src/agents/agent-scope.ts

@@ -1,4 +1,3 @@
-import os from "node:os";
 import path from "node:path";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolveStateDir } from "../config/paths.js";
@@ -8,7 +7,7 @@ import {
   parseAgentSessionKey,
 } from "../routing/session-key.js";
 import { resolveUserPath } from "../utils.js";
-import { DEFAULT_AGENT_WORKSPACE_DIR } from "./workspace.js";
+import { resolveDefaultAgentWorkspaceDir } from "./workspace.js";
 
 export { resolveAgentIdFromSessionKey } from "../routing/session-key.js";
 
@@ -176,9 +175,9 @@ export function resolveAgentWorkspaceDir(cfg: OpenClawConfig, agentId: string) {
     if (fallback) {
       return resolveUserPath(fallback);
     }
-    return DEFAULT_AGENT_WORKSPACE_DIR;
+    return resolveDefaultAgentWorkspaceDir(process.env);
   }
-  const stateDir = resolveStateDir(process.env, os.homedir);
+  const stateDir = resolveStateDir(process.env);
   return path.join(stateDir, `workspace-${id}`);
 }
 
@@ -188,6 +187,6 @@ export function resolveAgentDir(cfg: OpenClawConfig, agentId: string) {
   if (configured) {
     return resolveUserPath(configured);
   }
-  const root = resolveStateDir(process.env, os.homedir);
+  const root = resolveStateDir(process.env);
   return path.join(root, "agents", id, "agent");
 }

src/agents/workspace-run.test.ts

@@ -3,7 +3,7 @@ import { describe, expect, it } from "vitest";
 import type { OpenClawConfig } from "../config/config.js";
 import { resolveStateDir } from "../config/paths.js";
 import { resolveRunWorkspaceDir } from "./workspace-run.js";
-import { DEFAULT_AGENT_WORKSPACE_DIR } from "./workspace.js";
+import { resolveDefaultAgentWorkspaceDir } from "./workspace.js";
 
 describe("resolveRunWorkspaceDir", () => {
   it("resolves explicit workspace values without fallback", () => {
@@ -70,7 +70,7 @@ describe("resolveRunWorkspaceDir", () => {
     expect(result.usedFallback).toBe(true);
     expect(result.fallbackReason).toBe("missing");
     expect(result.agentId).toBe("main");
-    expect(result.workspaceDir).toBe(path.resolve(DEFAULT_AGENT_WORKSPACE_DIR));
+    expect(result.workspaceDir).toBe(path.resolve(resolveDefaultAgentWorkspaceDir(process.env)));
   });
 
   it("throws for malformed agent session keys", () => {

src/agents/workspace.defaults.test.ts

@@ -0,0 +1,17 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.resetModules();
+});
+
+describe("DEFAULT_AGENT_WORKSPACE_DIR", () => {
+  it("uses OPENCLAW_HOME at module import time", async () => {
+    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
+    vi.stubEnv("HOME", "/home/other");
+    vi.resetModules();
+
+    const mod = await import("./workspace.js");
+    expect(mod.DEFAULT_AGENT_WORKSPACE_DIR).toBe("/srv/openclaw-home/.openclaw/workspace");
+  });
+});

src/agents/workspace.test.ts

@@ -1,11 +1,24 @@
+import path from "node:path";
 import { describe, expect, it } from "vitest";
 import { makeTempWorkspace, writeWorkspaceFile } from "../test-helpers/workspace.js";
 import {
   DEFAULT_MEMORY_ALT_FILENAME,
   DEFAULT_MEMORY_FILENAME,
   loadWorkspaceBootstrapFiles,
+  resolveDefaultAgentWorkspaceDir,
 } from "./workspace.js";
 
+describe("resolveDefaultAgentWorkspaceDir", () => {
+  it("uses OPENCLAW_HOME for default workspace resolution", () => {
+    const dir = resolveDefaultAgentWorkspaceDir({
+      OPENCLAW_HOME: "/srv/openclaw-home",
+      HOME: "/home/other",
+    } as NodeJS.ProcessEnv);
+
+    expect(dir).toBe(path.join("/srv/openclaw-home", ".openclaw", "workspace"));
+  });
+});
+
 describe("loadWorkspaceBootstrapFiles", () => {
   it("includes MEMORY.md when present", async () => {
     const tempDir = await makeTempWorkspace("openclaw-workspace-");

src/agents/workspace.ts

@@ -1,6 +1,7 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 import { runCommandWithTimeout } from "../process/exec.js";
 import { isSubagentSessionKey } from "../routing/session-key.js";
 import { resolveUserPath } from "../utils.js";
@@ -10,11 +11,12 @@ export function resolveDefaultAgentWorkspaceDir(
   env: NodeJS.ProcessEnv = process.env,
   homedir: () => string = os.homedir,
 ): string {
+  const home = resolveRequiredHomeDir(env, homedir);
   const profile = env.OPENCLAW_PROFILE?.trim();
   if (profile && profile.toLowerCase() !== "default") {
-    return path.join(homedir(), ".openclaw", `workspace-${profile}`);
+    return path.join(home, ".openclaw", `workspace-${profile}`);
   }
-  return path.join(homedir(), ".openclaw", "workspace");
+  return path.join(home, ".openclaw", "workspace");
 }
 
 export const DEFAULT_AGENT_WORKSPACE_DIR = resolveDefaultAgentWorkspaceDir();

src/cli/profile.test.ts

@@ -82,6 +82,23 @@ describe("applyCliProfileEnv", () => {
     expect(env.OPENCLAW_GATEWAY_PORT).toBe("19099");
     expect(env.OPENCLAW_CONFIG_PATH).toBe(path.join("/custom", "openclaw.json"));
   });
+
+  it("uses OPENCLAW_HOME when deriving profile state dir", () => {
+    const env: Record<string, string | undefined> = {
+      OPENCLAW_HOME: "/srv/openclaw-home",
+      HOME: "/home/other",
+    };
+    applyCliProfileEnv({
+      profile: "work",
+      env,
+      homedir: () => "/home/fallback",
+    });
+
+    expect(env.OPENCLAW_STATE_DIR).toBe(path.join("/srv/openclaw-home", ".openclaw-work"));
+    expect(env.OPENCLAW_CONFIG_PATH).toBe(
+      path.join("/srv/openclaw-home", ".openclaw-work", "openclaw.json"),
+    );
+  });
 });
 
 describe("formatCliCommand", () => {

src/cli/profile.ts

@@ -1,5 +1,6 @@
 import os from "node:os";
 import path from "node:path";
+import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 import { isValidProfileName } from "./profile-utils.js";
 
 export type CliProfileParseResult =
@@ -87,9 +88,13 @@ export function parseCliProfileArgs(argv: string[]): CliProfileParseResult {
   return { ok: true, profile, argv: out };
 }
 
-function resolveProfileStateDir(profile: string, homedir: () => string): string {
+function resolveProfileStateDir(
+  profile: string,
+  env: Record<string, string | undefined>,
+  homedir: () => string,
+): string {
   const suffix = profile.toLowerCase() === "default" ? "" : `-${profile}`;
-  return path.join(homedir(), `.openclaw${suffix}`);
+  return path.join(resolveRequiredHomeDir(env as NodeJS.ProcessEnv, homedir), `.openclaw${suffix}`);
 }
 
 export function applyCliProfileEnv(params: {
@@ -107,7 +112,7 @@ export function applyCliProfileEnv(params: {
   // Convenience only: fill defaults, never override explicit env values.
   env.OPENCLAW_PROFILE = profile;
 
-  const stateDir = env.OPENCLAW_STATE_DIR?.trim() || resolveProfileStateDir(profile, homedir);
+  const stateDir = env.OPENCLAW_STATE_DIR?.trim() || resolveProfileStateDir(profile, env, homedir);
   if (!env.OPENCLAW_STATE_DIR?.trim()) {
     env.OPENCLAW_STATE_DIR = stateDir;
   }

src/commands/doctor-state-integrity.ts

@@ -11,6 +11,7 @@ import {
   resolveSessionTranscriptsDirForAgent,
   resolveStorePath,
 } from "../config/sessions.js";
+import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 import { note } from "../terminal/note.js";
 import { shortenHomePath } from "../utils.js";
 
@@ -139,7 +140,7 @@ export async function noteStateIntegrity(
   const warnings: string[] = [];
   const changes: string[] = [];
   const env = process.env;
-  const homedir = os.homedir;
+  const homedir = () => resolveRequiredHomeDir(env, os.homedir);
   const stateDir = resolveStateDir(env, homedir);
   const defaultStateDir = path.join(homedir(), ".openclaw");
   const oauthDir = resolveOAuthDir(env, stateDir);

src/config/agent-dirs.test.ts

@@ -0,0 +1,47 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "./types.js";
+import { findDuplicateAgentDirs } from "./agent-dirs.js";
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+});
+
+describe("resolveEffectiveAgentDir via findDuplicateAgentDirs", () => {
+  it("uses OPENCLAW_HOME for default agent dir resolution", () => {
+    // findDuplicateAgentDirs calls resolveEffectiveAgentDir internally.
+    // With a single agent there are no duplicates, but we can inspect the
+    // resolved dir indirectly by triggering a duplicate with two agents
+    // that both fall through to the same default dir — which can't happen
+    // since they have different IDs.  Instead we just verify no crash and
+    // that the env flows through by checking a two-agent config produces
+    // distinct dirs (no duplicates).
+    const cfg: OpenClawConfig = {
+      agents: {
+        list: [{ id: "alpha" }, { id: "beta" }],
+      },
+    };
+
+    const env = {
+      OPENCLAW_HOME: "/srv/openclaw-home",
+      HOME: "/home/other",
+    } as NodeJS.ProcessEnv;
+
+    const dupes = findDuplicateAgentDirs(cfg, { env });
+    expect(dupes).toHaveLength(0);
+  });
+
+  it("resolves agent dir under OPENCLAW_HOME state dir", () => {
+    // Force two agents to the same explicit agentDir to verify the path
+    // that doesn't use the default — then test the default path by
+    // checking that a single-agent config resolves without duplicates.
+    const cfg: OpenClawConfig = {};
+
+    const env = {
+      OPENCLAW_HOME: "/srv/openclaw-home",
+    } as NodeJS.ProcessEnv;
+
+    // No duplicates for a single default agent
+    const dupes = findDuplicateAgentDirs(cfg, { env });
+    expect(dupes).toHaveLength(0);
+  });
+});

src/config/agent-dirs.ts

@@ -1,6 +1,7 @@
 import os from "node:os";
 import path from "node:path";
 import type { OpenClawConfig } from "./types.js";
+import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 import { DEFAULT_AGENT_ID, normalizeAgentId } from "../routing/session-key.js";
 import { resolveUserPath } from "../utils.js";
 import { resolveStateDir } from "./paths.js";
@@ -68,7 +69,11 @@ function resolveEffectiveAgentDir(
   if (trimmed) {
     return resolveUserPath(trimmed);
   }
-  const root = resolveStateDir(deps?.env ?? process.env, deps?.homedir ?? os.homedir);
+  const env = deps?.env ?? process.env;
+  const root = resolveStateDir(
+    env,
+    deps?.homedir ?? (() => resolveRequiredHomeDir(env, os.homedir)),
+  );
   return path.join(root, "agents", id, "agent");
 }
 

src/config/config.nix-integration-u3-u5-u9.test.ts

@@ -49,6 +49,30 @@ describe("Nix integration (U3, U5, U9)", () => {
       });
     });
 
+    it("STATE_DIR respects OPENCLAW_HOME when state override is unset", async () => {
+      await withEnvOverride(
+        { OPENCLAW_HOME: "/custom/home", OPENCLAW_STATE_DIR: undefined },
+        async () => {
+          const { STATE_DIR } = await import("./config.js");
+          expect(STATE_DIR).toBe(path.resolve("/custom/home/.openclaw"));
+        },
+      );
+    });
+
+    it("CONFIG_PATH defaults to OPENCLAW_HOME/.openclaw/openclaw.json", async () => {
+      await withEnvOverride(
+        {
+          OPENCLAW_HOME: "/custom/home",
+          OPENCLAW_CONFIG_PATH: undefined,
+          OPENCLAW_STATE_DIR: undefined,
+        },
+        async () => {
+          const { CONFIG_PATH } = await import("./config.js");
+          expect(CONFIG_PATH).toBe(path.resolve("/custom/home/.openclaw/openclaw.json"));
+        },
+      );
+    });
+
     it("CONFIG_PATH defaults to ~/.openclaw/openclaw.json when env not set", async () => {
       await withEnvOverride(
         { OPENCLAW_CONFIG_PATH: undefined, OPENCLAW_STATE_DIR: undefined },

src/config/io.compat.test.ts

@@ -49,6 +49,16 @@ describe("config io paths", () => {
     });
   });
 
+  it("uses OPENCLAW_HOME for default config path", async () => {
+    await withTempHome(async (home) => {
+      const io = createConfigIO({
+        env: { OPENCLAW_HOME: path.join(home, "svc-home") } as NodeJS.ProcessEnv,
+        homedir: () => path.join(home, "ignored-home"),
+      });
+      expect(io.configPath).toBe(path.join(home, "svc-home", ".openclaw", "openclaw.json"));
+    });
+  });
+
   it("honors explicit OPENCLAW_CONFIG_PATH override", async () => {
     await withTempHome(async (home) => {
       const customPath = await writeConfig(home, ".openclaw", 20002, "custom.json");

src/config/io.ts

@@ -4,6 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { OpenClawConfig, ConfigFileSnapshot, LegacyConfigIssue } from "./types.js";
+import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 import {
   loadShellEnvFallback,
   resolveShellEnvFallbackTimeoutMs,
@@ -183,7 +184,8 @@ function normalizeDeps(overrides: ConfigIoDeps = {}): Required<ConfigIoDeps> {
     fs: overrides.fs ?? fs,
     json5: overrides.json5 ?? JSON5,
     env: overrides.env ?? process.env,
-    homedir: overrides.homedir ?? os.homedir,
+    homedir:
+      overrides.homedir ?? (() => resolveRequiredHomeDir(overrides.env ?? process.env, os.homedir)),
     configPath: overrides.configPath ?? "",
     logger: overrides.logger ?? console,
   };

src/config/paths.test.ts

@@ -44,6 +44,29 @@ describe("state + config path candidates", () => {
     expect(resolveStateDir(env, () => "/home/test")).toBe(path.resolve("/new/state"));
   });
 
+  it("uses OPENCLAW_HOME for default state/config locations", () => {
+    const env = {
+      OPENCLAW_HOME: "/srv/openclaw-home",
+    } as NodeJS.ProcessEnv;
+
+    expect(resolveStateDir(env)).toBe(path.join("/srv/openclaw-home", ".openclaw"));
+
+    const candidates = resolveDefaultConfigCandidates(env);
+    expect(candidates[0]).toBe(path.join("/srv/openclaw-home", ".openclaw", "openclaw.json"));
+  });
+
+  it("prefers OPENCLAW_HOME over HOME for default state/config locations", () => {
+    const env = {
+      OPENCLAW_HOME: "/srv/openclaw-home",
+      HOME: "/home/other",
+    } as NodeJS.ProcessEnv;
+
+    expect(resolveStateDir(env)).toBe(path.join("/srv/openclaw-home", ".openclaw"));
+
+    const candidates = resolveDefaultConfigCandidates(env);
+    expect(candidates[0]).toBe(path.join("/srv/openclaw-home", ".openclaw", "openclaw.json"));
+  });
+
   it("orders default config candidates in a stable order", () => {
     const home = "/home/test";
     const candidates = resolveDefaultConfigCandidates({} as NodeJS.ProcessEnv, () => home);

src/config/paths.ts

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import type { OpenClawConfig } from "./types.js";
+import { expandHomePrefix, resolveRequiredHomeDir } from "../infra/home-dir.js";
 
 /**
  * Nix mode detection: When OPENCLAW_NIX_MODE=1, the gateway is running under Nix.
@@ -21,23 +22,32 @@ const NEW_STATE_DIRNAME = ".openclaw";
 const CONFIG_FILENAME = "openclaw.json";
 const LEGACY_CONFIG_FILENAMES = ["clawdbot.json", "moltbot.json", "moldbot.json"] as const;
 
-function legacyStateDirs(homedir: () => string = os.homedir): string[] {
+function resolveDefaultHomeDir(): string {
+  return resolveRequiredHomeDir(process.env, os.homedir);
+}
+
+/** Build a homedir thunk that respects OPENCLAW_HOME for the given env. */
+function envHomedir(env: NodeJS.ProcessEnv): () => string {
+  return () => resolveRequiredHomeDir(env, os.homedir);
+}
+
+function legacyStateDirs(homedir: () => string = resolveDefaultHomeDir): string[] {
   return LEGACY_STATE_DIRNAMES.map((dir) => path.join(homedir(), dir));
 }
 
-function newStateDir(homedir: () => string = os.homedir): string {
+function newStateDir(homedir: () => string = resolveDefaultHomeDir): string {
   return path.join(homedir(), NEW_STATE_DIRNAME);
 }
 
-export function resolveLegacyStateDir(homedir: () => string = os.homedir): string {
+export function resolveLegacyStateDir(homedir: () => string = resolveDefaultHomeDir): string {
   return legacyStateDirs(homedir)[0] ?? newStateDir(homedir);
 }
 
-export function resolveLegacyStateDirs(homedir: () => string = os.homedir): string[] {
+export function resolveLegacyStateDirs(homedir: () => string = resolveDefaultHomeDir): string[] {
   return legacyStateDirs(homedir);
 }
 
-export function resolveNewStateDir(homedir: () => string = os.homedir): string {
+export function resolveNewStateDir(homedir: () => string = resolveDefaultHomeDir): string {
   return newStateDir(homedir);
 }
 
@@ -48,14 +58,15 @@ export function resolveNewStateDir(homedir: () => string = os.homedir): string {
  */
 export function resolveStateDir(
   env: NodeJS.ProcessEnv = process.env,
-  homedir: () => string = os.homedir,
+  homedir: () => string = envHomedir(env),
 ): string {
+  const effectiveHomedir = () => resolveRequiredHomeDir(env, homedir);
   const override = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
   if (override) {
-    return resolveUserPath(override);
+    return resolveUserPath(override, env, effectiveHomedir);
   }
-  const newDir = newStateDir(homedir);
-  const legacyDirs = legacyStateDirs(homedir);
+  const newDir = newStateDir(effectiveHomedir);
+  const legacyDirs = legacyStateDirs(effectiveHomedir);
   const hasNew = fs.existsSync(newDir);
   if (hasNew) {
     return newDir;
@@ -73,13 +84,21 @@ export function resolveStateDir(
   return newDir;
 }
 
-function resolveUserPath(input: string): string {
+function resolveUserPath(
+  input: string,
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = envHomedir(env),
+): string {
   const trimmed = input.trim();
   if (!trimmed) {
     return trimmed;
   }
   if (trimmed.startsWith("~")) {
-    const expanded = trimmed.replace(/^~(?=$|[\\/])/, os.homedir());
+    const expanded = expandHomePrefix(trimmed, {
+      home: resolveRequiredHomeDir(env, homedir),
+      env,
+      homedir,
+    });
     return path.resolve(expanded);
   }
   return path.resolve(trimmed);
@@ -94,11 +113,11 @@ export const STATE_DIR = resolveStateDir();
  */
 export function resolveCanonicalConfigPath(
   env: NodeJS.ProcessEnv = process.env,
-  stateDir: string = resolveStateDir(env, os.homedir),
+  stateDir: string = resolveStateDir(env, envHomedir(env)),
 ): string {
   const override = env.OPENCLAW_CONFIG_PATH?.trim() || env.CLAWDBOT_CONFIG_PATH?.trim();
   if (override) {
-    return resolveUserPath(override);
+    return resolveUserPath(override, env, envHomedir(env));
   }
   return path.join(stateDir, CONFIG_FILENAME);
 }
@@ -109,7 +128,7 @@ export function resolveCanonicalConfigPath(
  */
 export function resolveConfigPathCandidate(
   env: NodeJS.ProcessEnv = process.env,
-  homedir: () => string = os.homedir,
+  homedir: () => string = envHomedir(env),
 ): string {
   const candidates = resolveDefaultConfigCandidates(env, homedir);
   const existing = candidates.find((candidate) => {
@@ -130,12 +149,12 @@ export function resolveConfigPathCandidate(
  */
 export function resolveConfigPath(
   env: NodeJS.ProcessEnv = process.env,
-  stateDir: string = resolveStateDir(env, os.homedir),
-  homedir: () => string = os.homedir,
+  stateDir: string = resolveStateDir(env, envHomedir(env)),
+  homedir: () => string = envHomedir(env),
 ): string {
   const override = env.OPENCLAW_CONFIG_PATH?.trim();
   if (override) {
-    return resolveUserPath(override);
+    return resolveUserPath(override, env, homedir);
   }
   const stateOverride = env.OPENCLAW_STATE_DIR?.trim();
   const candidates = [
@@ -170,22 +189,23 @@ export const CONFIG_PATH = resolveConfigPathCandidate();
  */
 export function resolveDefaultConfigCandidates(
   env: NodeJS.ProcessEnv = process.env,
-  homedir: () => string = os.homedir,
+  homedir: () => string = envHomedir(env),
 ): string[] {
+  const effectiveHomedir = () => resolveRequiredHomeDir(env, homedir);
   const explicit = env.OPENCLAW_CONFIG_PATH?.trim() || env.CLAWDBOT_CONFIG_PATH?.trim();
   if (explicit) {
-    return [resolveUserPath(explicit)];
+    return [resolveUserPath(explicit, env, effectiveHomedir)];
   }
 
   const candidates: string[] = [];
   const openclawStateDir = env.OPENCLAW_STATE_DIR?.trim() || env.CLAWDBOT_STATE_DIR?.trim();
   if (openclawStateDir) {
-    const resolved = resolveUserPath(openclawStateDir);
+    const resolved = resolveUserPath(openclawStateDir, env, effectiveHomedir);
     candidates.push(path.join(resolved, CONFIG_FILENAME));
     candidates.push(...LEGACY_CONFIG_FILENAMES.map((name) => path.join(resolved, name)));
   }
 
-  const defaultDirs = [newStateDir(homedir), ...legacyStateDirs(homedir)];
+  const defaultDirs = [newStateDir(effectiveHomedir), ...legacyStateDirs(effectiveHomedir)];
   for (const dir of defaultDirs) {
     candidates.push(path.join(dir, CONFIG_FILENAME));
     candidates.push(...LEGACY_CONFIG_FILENAMES.map((name) => path.join(dir, name)));
@@ -217,18 +237,18 @@ const OAUTH_FILENAME = "oauth.json";
  */
 export function resolveOAuthDir(
   env: NodeJS.ProcessEnv = process.env,
-  stateDir: string = resolveStateDir(env, os.homedir),
+  stateDir: string = resolveStateDir(env, envHomedir(env)),
 ): string {
   const override = env.OPENCLAW_OAUTH_DIR?.trim();
   if (override) {
-    return resolveUserPath(override);
+    return resolveUserPath(override, env, envHomedir(env));
   }
   return path.join(stateDir, "credentials");
 }
 
 export function resolveOAuthPath(
   env: NodeJS.ProcessEnv = process.env,
-  stateDir: string = resolveStateDir(env, os.homedir),
+  stateDir: string = resolveStateDir(env, envHomedir(env)),
 ): string {
   return path.join(resolveOAuthDir(env, stateDir), OAUTH_FILENAME);
 }

src/config/sessions/paths.test.ts

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolveStorePath } from "./paths.js";
+
+describe("resolveStorePath", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("uses OPENCLAW_HOME for tilde expansion", () => {
+    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
+    vi.stubEnv("HOME", "/home/other");
+
+    const resolved = resolveStorePath("~/.openclaw/agents/{agentId}/sessions/sessions.json", {
+      agentId: "research",
+    });
+
+    expect(resolved).toBe(
+      path.resolve("/srv/openclaw-home/.openclaw/agents/research/sessions/sessions.json"),
+    );
+  });
+});

src/config/sessions/paths.ts

@@ -1,13 +1,14 @@
 import os from "node:os";
 import path from "node:path";
 import type { SessionEntry } from "./types.js";
+import { expandHomePrefix, resolveRequiredHomeDir } from "../../infra/home-dir.js";
 import { DEFAULT_AGENT_ID, normalizeAgentId } from "../../routing/session-key.js";
 import { resolveStateDir } from "../paths.js";
 
 function resolveAgentSessionsDir(
   agentId?: string,
   env: NodeJS.ProcessEnv = process.env,
-  homedir: () => string = os.homedir,
+  homedir: () => string = () => resolveRequiredHomeDir(env, os.homedir),
 ): string {
   const root = resolveStateDir(env, homedir);
   const id = normalizeAgentId(agentId ?? DEFAULT_AGENT_ID);
@@ -16,7 +17,7 @@ function resolveAgentSessionsDir(
 
 export function resolveSessionTranscriptsDir(
   env: NodeJS.ProcessEnv = process.env,
-  homedir: () => string = os.homedir,
+  homedir: () => string = () => resolveRequiredHomeDir(env, os.homedir),
 ): string {
   return resolveAgentSessionsDir(DEFAULT_AGENT_ID, env, homedir);
 }
@@ -24,7 +25,7 @@ export function resolveSessionTranscriptsDir(
 export function resolveSessionTranscriptsDirForAgent(
   agentId?: string,
   env: NodeJS.ProcessEnv = process.env,
-  homedir: () => string = os.homedir,
+  homedir: () => string = () => resolveRequiredHomeDir(env, os.homedir),
 ): string {
   return resolveAgentSessionsDir(agentId, env, homedir);
 }
@@ -66,12 +67,24 @@ export function resolveStorePath(store?: string, opts?: { agentId?: string }) {
   if (store.includes("{agentId}")) {
     const expanded = store.replaceAll("{agentId}", agentId);
     if (expanded.startsWith("~")) {
-      return path.resolve(expanded.replace(/^~(?=$|[\\/])/, os.homedir()));
+      return path.resolve(
+        expandHomePrefix(expanded, {
+          home: resolveRequiredHomeDir(process.env, os.homedir),
+          env: process.env,
+          homedir: os.homedir,
+        }),
+      );
     }
     return path.resolve(expanded);
   }
   if (store.startsWith("~")) {
-    return path.resolve(store.replace(/^~(?=$|[\\/])/, os.homedir()));
+    return path.resolve(
+      expandHomePrefix(store, {
+        home: resolveRequiredHomeDir(process.env, os.homedir),
+        env: process.env,
+        homedir: os.homedir,
+      }),
+    );
   }
   return path.resolve(store);
 }

src/cron/store.test.ts

@@ -1,8 +1,8 @@
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
-import { describe, expect, it } from "vitest";
-import { loadCronStore } from "./store.js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { loadCronStore, resolveCronStorePath } from "./store.js";
 
 async function makeStorePath() {
   const dir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-cron-store-"));
@@ -15,6 +15,20 @@ async function makeStorePath() {
   };
 }
 
+describe("resolveCronStorePath", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("uses OPENCLAW_HOME for tilde expansion", () => {
+    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
+    vi.stubEnv("HOME", "/home/other");
+
+    const result = resolveCronStorePath("~/cron/jobs.json");
+    expect(result).toBe(path.resolve("/srv/openclaw-home", "cron", "jobs.json"));
+  });
+});
+
 describe("cron store", () => {
   it("returns empty store when file does not exist", async () => {
     const store = await makeStorePath();

src/cron/store.ts

@@ -1,8 +1,8 @@
 import JSON5 from "json5";
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
 import type { CronStoreFile } from "./types.js";
+import { expandHomePrefix } from "../infra/home-dir.js";
 import { CONFIG_DIR } from "../utils.js";
 
 export const DEFAULT_CRON_DIR = path.join(CONFIG_DIR, "cron");
@@ -12,7 +12,7 @@ export function resolveCronStorePath(storePath?: string) {
   if (storePath?.trim()) {
     const raw = storePath.trim();
     if (raw.startsWith("~")) {
-      return path.resolve(raw.replace("~", os.homedir()));
+      return path.resolve(expandHomePrefix(raw));
     }
     return path.resolve(raw);
   }

src/gateway/session-utils.fs.test.ts

@@ -1,12 +1,13 @@
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { afterEach, beforeEach, describe, expect, test } from "vitest";
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import {
   readFirstUserMessageFromTranscript,
   readLastMessagePreviewFromTranscript,
   readSessionMessages,
   readSessionPreviewItemsFromTranscript,
+  resolveSessionTranscriptCandidates,
 } from "./session-utils.fs.js";
 
 describe("readFirstUserMessageFromTranscript", () => {
@@ -489,3 +490,18 @@ describe("readSessionPreviewItemsFromTranscript", () => {
     expect(result[0]?.text.endsWith("...")).toBe(true);
   });
 });
+
+describe("resolveSessionTranscriptCandidates", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  test("fallback candidate uses OPENCLAW_HOME instead of os.homedir()", () => {
+    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
+    vi.stubEnv("HOME", "/home/other");
+
+    const candidates = resolveSessionTranscriptCandidates("sess-1", undefined);
+    const fallback = candidates[candidates.length - 1];
+    expect(fallback).toBe(path.join("/srv/openclaw-home", ".openclaw", "sessions", "sess-1.jsonl"));
+  });
+});

src/gateway/session-utils.fs.ts

@@ -3,6 +3,7 @@ import os from "node:os";
 import path from "node:path";
 import type { SessionPreviewItem } from "./session-utils.types.js";
 import { resolveSessionTranscriptPath } from "../config/sessions.js";
+import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 import { extractToolCallNames, hasToolCall } from "../utils/transcript-tools.js";
 import { stripEnvelope } from "./chat-sanitize.js";
 
@@ -70,7 +71,7 @@ export function resolveSessionTranscriptCandidates(
   if (agentId) {
     candidates.push(resolveSessionTranscriptPath(sessionId, agentId));
   }
-  const home = os.homedir();
+  const home = resolveRequiredHomeDir(process.env, os.homedir);
   candidates.push(path.join(home, ".openclaw", "sessions", `${sessionId}.jsonl`));
   return candidates;
 }

src/infra/home-dir.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, it } from "vitest";
+import { expandHomePrefix, resolveEffectiveHomeDir, resolveRequiredHomeDir } from "./home-dir.js";
+
+describe("resolveEffectiveHomeDir", () => {
+  it("prefers OPENCLAW_HOME over HOME and USERPROFILE", () => {
+    const env = {
+      OPENCLAW_HOME: "/srv/openclaw-home",
+      HOME: "/home/other",
+      USERPROFILE: "C:/Users/other",
+    } as NodeJS.ProcessEnv;
+
+    expect(resolveEffectiveHomeDir(env, () => "/fallback")).toBe("/srv/openclaw-home");
+  });
+
+  it("falls back to HOME then USERPROFILE then homedir", () => {
+    expect(resolveEffectiveHomeDir({ HOME: "/home/alice" } as NodeJS.ProcessEnv)).toBe(
+      "/home/alice",
+    );
+    expect(resolveEffectiveHomeDir({ USERPROFILE: "C:/Users/alice" } as NodeJS.ProcessEnv)).toBe(
+      "C:/Users/alice",
+    );
+    expect(resolveEffectiveHomeDir({} as NodeJS.ProcessEnv, () => "/fallback")).toBe("/fallback");
+  });
+
+  it("expands OPENCLAW_HOME when set to ~", () => {
+    const env = {
+      OPENCLAW_HOME: "~/svc",
+      HOME: "/home/alice",
+    } as NodeJS.ProcessEnv;
+
+    expect(resolveEffectiveHomeDir(env)).toBe("/home/alice/svc");
+  });
+});
+
+describe("resolveRequiredHomeDir", () => {
+  it("returns cwd when no home source is available", () => {
+    expect(
+      resolveRequiredHomeDir({} as NodeJS.ProcessEnv, () => {
+        throw new Error("no home");
+      }),
+    ).toBe(process.cwd());
+  });
+
+  it("returns cwd when OPENCLAW_HOME is tilde-only and no fallback home exists", () => {
+    expect(
+      resolveRequiredHomeDir({ OPENCLAW_HOME: "~" } as NodeJS.ProcessEnv, () => {
+        throw new Error("no home");
+      }),
+    ).toBe(process.cwd());
+  });
+});
+
+describe("expandHomePrefix", () => {
+  it("expands tilde using effective home", () => {
+    const value = expandHomePrefix("~/x", {
+      env: { OPENCLAW_HOME: "/srv/openclaw-home" } as NodeJS.ProcessEnv,
+    });
+    expect(value).toBe("/srv/openclaw-home/x");
+  });
+
+  it("keeps non-tilde values unchanged", () => {
+    expect(expandHomePrefix("/tmp/x")).toBe("/tmp/x");
+  });
+});

src/infra/home-dir.ts

@@ -0,0 +1,71 @@
+import os from "node:os";
+
+function normalize(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
+export function resolveEffectiveHomeDir(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string | undefined {
+  const explicitHome = normalize(env.OPENCLAW_HOME);
+  if (explicitHome) {
+    if (explicitHome === "~" || explicitHome.startsWith("~/") || explicitHome.startsWith("~\\")) {
+      const fallbackHome =
+        normalize(env.HOME) ?? normalize(env.USERPROFILE) ?? normalizeSafe(homedir);
+      if (fallbackHome) {
+        return explicitHome.replace(/^~(?=$|[\\/])/, fallbackHome);
+      }
+      return undefined;
+    }
+    return explicitHome;
+  }
+
+  const envHome = normalize(env.HOME);
+  if (envHome) {
+    return envHome;
+  }
+
+  const userProfile = normalize(env.USERPROFILE);
+  if (userProfile) {
+    return userProfile;
+  }
+
+  return normalizeSafe(homedir);
+}
+
+function normalizeSafe(homedir: () => string): string | undefined {
+  try {
+    return normalize(homedir());
+  } catch {
+    return undefined;
+  }
+}
+
+export function resolveRequiredHomeDir(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: () => string = os.homedir,
+): string {
+  return resolveEffectiveHomeDir(env, homedir) ?? process.cwd();
+}
+
+export function expandHomePrefix(
+  input: string,
+  opts?: {
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+    homedir?: () => string;
+  },
+): string {
+  if (!input.startsWith("~")) {
+    return input;
+  }
+  const home =
+    normalize(opts?.home) ??
+    resolveEffectiveHomeDir(opts?.env ?? process.env, opts?.homedir ?? os.homedir);
+  if (!home) {
+    return input;
+  }
+  return input.replace(/^~(?=$|[\\/])/, home);
+}

src/pairing/pairing-store.ts

@@ -6,6 +6,7 @@ import lockfile from "proper-lockfile";
 import type { ChannelId, ChannelPairingAdapter } from "../channels/plugins/types.js";
 import { getPairingAdapter } from "../channels/plugins/pairing.js";
 import { resolveOAuthDir, resolveStateDir } from "../config/paths.js";
+import { resolveRequiredHomeDir } from "../infra/home-dir.js";
 
 const PAIRING_CODE_LENGTH = 8;
 const PAIRING_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
@@ -43,7 +44,7 @@ type AllowFromStore = {
 };
 
 function resolveCredentialsDir(env: NodeJS.ProcessEnv = process.env): string {
-  const stateDir = resolveStateDir(env, os.homedir);
+  const stateDir = resolveStateDir(env, () => resolveRequiredHomeDir(env, os.homedir));
   return resolveOAuthDir(env, stateDir);
 }
 

src/utils.test.ts

@@ -10,8 +10,11 @@ import {
   normalizeE164,
   normalizePath,
   resolveConfigDir,
+  resolveHomeDir,
   resolveJidToE164,
   resolveUserPath,
+  shortenHomeInString,
+  shortenHomePath,
   sleep,
   toWhatsappJid,
   withWhatsAppPrefix,
@@ -134,6 +137,43 @@ describe("resolveConfigDir", () => {
   });
 });
 
+describe("resolveHomeDir", () => {
+  it("prefers OPENCLAW_HOME over HOME", () => {
+    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
+    vi.stubEnv("HOME", "/home/other");
+
+    expect(resolveHomeDir()).toBe("/srv/openclaw-home");
+
+    vi.unstubAllEnvs();
+  });
+});
+
+describe("shortenHomePath", () => {
+  it("uses $OPENCLAW_HOME prefix when OPENCLAW_HOME is set", () => {
+    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
+    vi.stubEnv("HOME", "/home/other");
+
+    expect(shortenHomePath("/srv/openclaw-home/.openclaw/openclaw.json")).toBe(
+      "$OPENCLAW_HOME/.openclaw/openclaw.json",
+    );
+
+    vi.unstubAllEnvs();
+  });
+});
+
+describe("shortenHomeInString", () => {
+  it("uses $OPENCLAW_HOME replacement when OPENCLAW_HOME is set", () => {
+    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
+    vi.stubEnv("HOME", "/home/other");
+
+    expect(shortenHomeInString("config: /srv/openclaw-home/.openclaw/openclaw.json")).toBe(
+      "config: $OPENCLAW_HOME/.openclaw/openclaw.json",
+    );
+
+    vi.unstubAllEnvs();
+  });
+});
+
 describe("resolveJidToE164", () => {
   it("resolves @lid via lidLookup when mapping file is missing", async () => {
     const lidLookup = {
@@ -165,6 +205,15 @@ describe("resolveUserPath", () => {
     expect(resolveUserPath("tmp/dir")).toBe(path.resolve("tmp/dir"));
   });
 
+  it("prefers OPENCLAW_HOME for tilde expansion", () => {
+    vi.stubEnv("OPENCLAW_HOME", "/srv/openclaw-home");
+    vi.stubEnv("HOME", "/home/other");
+
+    expect(resolveUserPath("~/openclaw")).toBe(path.resolve("/srv/openclaw-home", "openclaw"));
+
+    vi.unstubAllEnvs();
+  });
+
   it("keeps blank paths blank", () => {
     expect(resolveUserPath("")).toBe("");
     expect(resolveUserPath("   ")).toBe("");

src/utils.ts

@@ -3,6 +3,11 @@ import os from "node:os";
 import path from "node:path";
 import { resolveOAuthDir } from "./config/paths.js";
 import { logVerbose, shouldLogVerbose } from "./globals.js";
+import {
+  expandHomePrefix,
+  resolveEffectiveHomeDir,
+  resolveRequiredHomeDir,
+} from "./infra/home-dir.js";
 
 export async function ensureDir(dir: string) {
   await fs.promises.mkdir(dir, { recursive: true });
@@ -239,7 +244,11 @@ export function resolveUserPath(input: string): string {
     return trimmed;
   }
   if (trimmed.startsWith("~")) {
-    const expanded = trimmed.replace(/^~(?=$|[\\/])/, os.homedir());
+    const expanded = expandHomePrefix(trimmed, {
+      home: resolveRequiredHomeDir(process.env, os.homedir),
+      env: process.env,
+      homedir: os.homedir,
+    });
     return path.resolve(expanded);
   }
   return path.resolve(trimmed);
@@ -253,7 +262,7 @@ export function resolveConfigDir(
   if (override) {
     return resolveUserPath(override);
   }
-  const newDir = path.join(homedir(), ".openclaw");
+  const newDir = path.join(resolveRequiredHomeDir(env, homedir), ".openclaw");
   try {
     const hasNew = fs.existsSync(newDir);
     if (hasNew) {
@@ -266,35 +275,35 @@ export function resolveConfigDir(
 }
 
 export function resolveHomeDir(): string | undefined {
-  const envHome = process.env.HOME?.trim();
-  if (envHome) {
-    return envHome;
-  }
-  const envProfile = process.env.USERPROFILE?.trim();
-  if (envProfile) {
-    return envProfile;
-  }
-  try {
-    const home = os.homedir();
-    return home?.trim() ? home : undefined;
-  } catch {
+  return resolveEffectiveHomeDir(process.env, os.homedir);
+}
+
+function resolveHomeDisplayPrefix(): { home: string; prefix: string } | undefined {
+  const home = resolveHomeDir();
+  if (!home) {
     return undefined;
   }
+  const explicitHome = process.env.OPENCLAW_HOME?.trim();
+  if (explicitHome) {
+    return { home, prefix: "$OPENCLAW_HOME" };
+  }
+  return { home, prefix: "~" };
 }
 
 export function shortenHomePath(input: string): string {
   if (!input) {
     return input;
   }
-  const home = resolveHomeDir();
-  if (!home) {
+  const display = resolveHomeDisplayPrefix();
+  if (!display) {
     return input;
   }
+  const { home, prefix } = display;
   if (input === home) {
-    return "~";
+    return prefix;
   }
-  if (input.startsWith(`${home}/`)) {
-    return `~${input.slice(home.length)}`;
+  if (input.startsWith(`${home}/`) || input.startsWith(`${home}\\`)) {
+    return `${prefix}${input.slice(home.length)}`;
   }
   return input;
 }
@@ -303,11 +312,11 @@ export function shortenHomeInString(input: string): string {
   if (!input) {
     return input;
   }
-  const home = resolveHomeDir();
-  if (!home) {
+  const display = resolveHomeDisplayPrefix();
+  if (!display) {
     return input;
   }
-  return input.split(home).join("~");
+  return input.split(display.home).join(display.prefix);
 }
 
 export function displayPath(input: string): string {