fix: warn on windows cloud synced state dirs

haruaiclone-droid · haruaiclone-droid · commit 81eaec14bf1e · 2026-07-01T15:45:32.000+09:00
diff --git a/docs/gateway/doctor.md b/docs/gateway/doctor.md
@@ -397,7 +397,7 @@ That stages grounded durable candidates into the short-term dreaming store while
 
     - **State dir missing**: warns about catastrophic state loss, prompts to recreate the directory, and reminds you that it cannot recover missing data.
     - **State dir permissions**: verifies writability; offers to repair permissions (and emits a `chown` hint when owner/group mismatch is detected).
-    - **macOS cloud-synced state dir**: warns when state resolves under iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) or `~/Library/CloudStorage/...` because sync-backed paths can cause slower I/O and lock/sync races.
+    - **Cloud-synced state dir**: warns when macOS state resolves under iCloud Drive (`~/Library/Mobile Documents/com~apple~CloudDocs/...`) or `~/Library/CloudStorage/...`, or when Windows state resolves under OneDrive/Dropbox/Google Drive/iCloud Drive, because sync-backed paths can cause slower I/O and lock/sync races.
     - **Linux SD or eMMC state dir**: warns when state resolves to an `mmcblk*` mount source, because SD or eMMC-backed random I/O can be slower and wear faster under session and credential writes.
     - **Linux volatile state dir**: warns when state resolves to `tmpfs` or `ramfs`, because sessions, credentials, config, and SQLite state with its WAL/journal sidecars will disappear on reboot. Docker `overlay` mounts are intentionally not flagged because their writable layers persist across host reboots while the container remains.
     - **Session dirs missing**: `sessions/` and the session store directory are required to persist history and avoid `ENOENT` crashes.
diff --git a/docs/platforms/windows.md b/docs/platforms/windows.md
@@ -130,6 +130,12 @@ a generated `gateway.vbs` WScript wrapper so the background Gateway does not ope
 a visible console window. If task creation is denied, OpenClaw falls back to a
 per-user Startup-folder login item.
 
+Keep `OPENCLAW_STATE_DIR` on a local non-synced path such as
+`%USERPROFILE%\.openclaw`. Avoid OneDrive, Dropbox, Google Drive, and iCloud
+Drive for Gateway state because Files On-Demand, sync locks, and hydration delays
+can slow startup or block SQLite/session writes. `openclaw doctor` warns when it
+detects common Windows cloud-synced state paths.
+
 To install the Gateway service:
 
 ```powershell
diff --git a/src/commands/doctor-state-integrity.cloud-storage.test.ts b/src/commands/doctor-state-integrity.cloud-storage.test.ts
@@ -2,7 +2,12 @@
 import os from "node:os";
 import path from "node:path";
 import { describe, expect, it, vi } from "vitest";
-import { detectMacCloudSyncedStateDir } from "./doctor-state-integrity.js";
+import {
+  detectMacCloudSyncedStateDir,
+  detectWindowsCloudSyncedStateDir,
+  stateIntegrityIssueToHealthFinding,
+  stateIntegrityIssueToRepairEffect,
+} from "./doctor-state-integrity.js";
 
 describe("detectMacCloudSyncedStateDir", () => {
   const home = "/Users/tester";
@@ -127,3 +132,119 @@ describe("detectMacCloudSyncedStateDir", () => {
     expect(result).toBeNull();
   });
 });
+
+describe("detectWindowsCloudSyncedStateDir", () => {
+  const winPath = path.win32;
+  const home = "C:\\Users\\tester";
+
+  it("detects state dir under OneDrive env root", () => {
+    const oneDriveRoot = winPath.join(home, "OneDrive - Example");
+    const stateDir = winPath.join(oneDriveRoot, "Desktop", "OpenClaw", ".openclaw");
+
+    const result = detectWindowsCloudSyncedStateDir(stateDir, {
+      platform: "win32",
+      homedir: home,
+      env: { OneDriveCommercial: oneDriveRoot },
+    });
+
+    expect(result).toEqual({
+      path: winPath.resolve(stateDir),
+      storage: "OneDrive",
+    });
+  });
+
+  it("detects common Windows cloud storage folders under the user profile", () => {
+    const stateDir = winPath.join(home, "Dropbox", "OpenClaw", ".openclaw");
+
+    const result = detectWindowsCloudSyncedStateDir(stateDir, {
+      platform: "win32",
+      homedir: home,
+      env: {},
+    });
+
+    expect(result).toEqual({
+      path: winPath.resolve(stateDir),
+      storage: "Dropbox",
+    });
+  });
+
+  it("detects personal and organization OneDrive folders under the user profile", () => {
+    for (const folderName of ["OneDrive", "OneDrive - Contoso"]) {
+      const stateDir = winPath.join(home, folderName, "OpenClaw", ".openclaw");
+
+      const result = detectWindowsCloudSyncedStateDir(stateDir, {
+        platform: "win32",
+        homedir: home,
+        env: {},
+      });
+
+      expect(result).toEqual({
+        path: winPath.resolve(stateDir),
+        storage: "OneDrive",
+      });
+    }
+  });
+
+  it("detects cloud-synced target when state dir resolves via reparse point", () => {
+    const junctionPath = winPath.join(home, ".openclaw");
+    const resolvedCloudPath = winPath.join(home, "OneDrive", "OpenClaw", ".openclaw");
+
+    const result = detectWindowsCloudSyncedStateDir(junctionPath, {
+      platform: "win32",
+      homedir: home,
+      env: {},
+      resolveRealPath: () => resolvedCloudPath,
+    });
+
+    expect(result).toEqual({
+      path: winPath.resolve(resolvedCloudPath),
+      storage: "OneDrive",
+    });
+  });
+
+  it("ignores cloud-synced prefix when resolved target is local", () => {
+    const junctionPath = winPath.join(home, "OneDrive", "OpenClaw", ".openclaw");
+    const resolvedLocalPath = winPath.join(home, ".openclaw");
+
+    const result = detectWindowsCloudSyncedStateDir(junctionPath, {
+      platform: "win32",
+      homedir: home,
+      env: {},
+      resolveRealPath: () => resolvedLocalPath,
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("returns null outside Windows", () => {
+    const stateDir = winPath.join(home, "OneDrive", "OpenClaw", ".openclaw");
+
+    const result = detectWindowsCloudSyncedStateDir(stateDir, {
+      platform: "linux",
+      homedir: home,
+      env: {},
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("maps Windows cloud state dir findings to warning and dry-run effect", () => {
+    const issue = {
+      kind: "windows-cloud-state-dir" as const,
+      path: winPath.join(home, "OneDrive", "OpenClaw", ".openclaw"),
+      storage: "OneDrive",
+    };
+
+    expect(stateIntegrityIssueToHealthFinding(issue)).toMatchObject({
+      checkId: "core/doctor/state-integrity",
+      severity: "warning",
+      path: issue.path,
+    });
+    expect(stateIntegrityIssueToRepairEffect(issue)).toEqual({
+      kind: "state",
+      action: "would-recommend-moving-state-dir",
+      target: issue.path,
+      dryRunSafe: true,
+    });
+  });
+});
diff --git a/src/commands/doctor-state-integrity.ts b/src/commands/doctor-state-integrity.ts
@@ -91,6 +91,11 @@ export type StateIntegrityHealthIssue =
       path: string;
       storage: string;
     }
+  | {
+      kind: "windows-cloud-state-dir";
+      path: string;
+      storage: string;
+    }
   | {
       kind: "linux-sd-state-dir";
       path: string;
@@ -459,6 +464,20 @@ function isPathUnderRootWithPathOps(
   );
 }
 
+function isWindowsPathUnderRoot(targetPath: string, rootPath: string): boolean {
+  const winPath = path.win32;
+  const normalizedTarget = winPath.resolve(targetPath).toLowerCase();
+  const normalizedRoot = winPath.resolve(rootPath).toLowerCase();
+  const rootToken = winPath.parse(normalizedRoot).root;
+  if (normalizedRoot === rootToken) {
+    return normalizedTarget.startsWith(rootToken);
+  }
+  return (
+    normalizedTarget === normalizedRoot ||
+    normalizedTarget.startsWith(`${normalizedRoot}${winPath.sep}`)
+  );
+}
+
 function findLinuxMountInfoEntryForPath(
   targetPath: string,
   entries: LinuxMountInfoEntry[],
@@ -633,6 +652,75 @@ export function formatLinuxVolatileStateDirWarning(
   ].join("\n");
 }
 
+type WindowsCloudSyncedStorage = "OneDrive" | "Dropbox" | "Google Drive" | "iCloud Drive";
+
+function windowsCloudStorageFromHomeChild(name: string): WindowsCloudSyncedStorage | null {
+  const normalized = name.trim().toLowerCase();
+  if (normalized === "onedrive" || normalized.startsWith("onedrive - ")) {
+    return "OneDrive";
+  }
+  if (normalized === "dropbox" || normalized.startsWith("dropbox ")) {
+    return "Dropbox";
+  }
+  if (normalized === "google drive" || normalized === "my drive") {
+    return "Google Drive";
+  }
+  if (normalized === "iclouddrive" || normalized === "icloud drive") {
+    return "iCloud Drive";
+  }
+  return null;
+}
+
+/** Detects Windows state directories under common cloud-synced storage roots. */
+export function detectWindowsCloudSyncedStateDir(
+  stateDir: string,
+  deps?: {
+    platform?: NodeJS.Platform;
+    homedir?: string;
+    env?: NodeJS.ProcessEnv;
+    resolveRealPath?: (targetPath: string) => string | null;
+  },
+): {
+  path: string;
+  storage: WindowsCloudSyncedStorage;
+} | null {
+  const platform = deps?.platform ?? process.platform;
+  if (platform !== "win32") {
+    return null;
+  }
+
+  const winPath = path.win32;
+  const realPath = (deps?.resolveRealPath ?? tryResolveRealPath)(stateDir);
+  // Prefer the resolved target when available so a synced symlink/reparse-point
+  // prefix does not misclassify local state dirs as cloud-synced.
+  const candidate = winPath.resolve(realPath ?? stateDir);
+  const env = deps?.env ?? process.env;
+  const oneDriveRoots = [
+    env.OneDrive,
+    env.OneDriveConsumer,
+    env.OneDriveCommercial,
+    env.ONEDRIVE,
+  ].flatMap((value) => {
+    const trimmed = value?.trim();
+    return trimmed ? [trimmed] : [];
+  });
+  for (const root of oneDriveRoots) {
+    if (isWindowsPathUnderRoot(candidate, root)) {
+      return { path: candidate, storage: "OneDrive" };
+    }
+  }
+
+  const homedir = deps?.homedir ?? os.homedir();
+  const homeRoot = winPath.resolve(homedir);
+  const relativeToHome = winPath.relative(homeRoot, candidate);
+  if (!relativeToHome || relativeToHome.startsWith("..") || winPath.isAbsolute(relativeToHome)) {
+    return null;
+  }
+  const [firstSegment] = relativeToHome.split(/[\\/]+/);
+  const storage = firstSegment ? windowsCloudStorageFromHomeChild(firstSegment) : null;
+  return storage ? { path: candidate, storage } : null;
+}
+
 /** Detects macOS state directories under iCloud Drive or CloudStorage providers. */
 export function detectMacCloudSyncedStateDir(
   stateDir: string,
@@ -785,6 +873,15 @@ export function detectStateIntegrityHealthIssues(
     });
   }
 
+  const windowsCloudSyncedStateDir = detectWindowsCloudSyncedStateDir(stateDir);
+  if (windowsCloudSyncedStateDir) {
+    issues.push({
+      kind: "windows-cloud-state-dir",
+      path: windowsCloudSyncedStateDir.path,
+      storage: windowsCloudSyncedStateDir.storage,
+    });
+  }
+
   const linuxSdBackedStateDir = detectLinuxSdBackedStateDir(stateDir);
   if (linuxSdBackedStateDir) {
     issues.push({
@@ -888,6 +985,15 @@ export function stateIntegrityIssueToHealthFinding(
         path: issue.path,
         fixHint: "Move OPENCLAW_STATE_DIR to local non-synced storage such as ~/.openclaw.",
       };
+    case "windows-cloud-state-dir":
+      return {
+        checkId: STATE_INTEGRITY_CHECK_ID,
+        severity: "warning",
+        message: `State directory is under Windows cloud-synced storage (${issue.storage}), which can cause slow I/O and sync races.`,
+        path: issue.path,
+        fixHint:
+          "Move OPENCLAW_STATE_DIR to a local non-synced path such as %USERPROFILE%\\.openclaw.",
+      };
     case "linux-sd-state-dir":
       return {
         checkId: STATE_INTEGRITY_CHECK_ID,
@@ -968,6 +1074,7 @@ export function stateIntegrityIssueToRepairEffect(
 ): HealthRepairEffect {
   switch (issue.kind) {
     case "mac-cloud-state-dir":
+    case "windows-cloud-state-dir":
     case "linux-sd-state-dir":
     case "linux-volatile-state-dir":
       return {
@@ -1048,6 +1155,7 @@ export async function noteStateIntegrity(
   const displayConfigPath = configPath ? shortenHomePath(configPath) : undefined;
   const requireOAuthDir = shouldRequireOAuthDir(cfg, env);
   const cloudSyncedStateDir = detectMacCloudSyncedStateDir(stateDir);
+  const windowsCloudSyncedStateDir = detectWindowsCloudSyncedStateDir(stateDir);
   const linuxSdBackedStateDir = detectLinuxSdBackedStateDir(stateDir);
   const linuxVolatileStateDir = detectLinuxVolatileStateDir(stateDir);
   const suppressOrphanTranscriptWarning = shouldSuppressOrphanTranscriptWarning(cfg, agentId);
@@ -1062,6 +1170,16 @@ export async function noteStateIntegrity(
       ].join("\n"),
     );
   }
+  if (windowsCloudSyncedStateDir) {
+    warnings.push(
+      [
+        `- State directory is under Windows cloud-synced storage (${displayStateDir}; ${windowsCloudSyncedStateDir.storage}).`,
+        "- This can cause slow I/O and sync/lock races for sessions and credentials.",
+        "- Prefer a local non-synced state dir (for example: %USERPROFILE%\\.openclaw).",
+        `  Set locally: $env:OPENCLAW_STATE_DIR="$env:USERPROFILE\\.openclaw"; ${formatCliCommand("openclaw doctor")}`,
+      ].join("\n"),
+    );
+  }
   if (linuxSdBackedStateDir) {
     warnings.push(formatLinuxSdBackedStateDirWarning(displayStateDir, linuxSdBackedStateDir));
   }
diff --git a/test/vitest/vitest.commands-light-paths.mjs b/test/vitest/vitest.commands-light-paths.mjs
@@ -14,6 +14,7 @@ const commandsLightEntries = [
     source: "src/commands/doctor-gateway-auth-token.ts",
     test: "src/commands/doctor-gateway-auth-token.test.ts",
   },
+  { test: "src/commands/doctor-state-integrity.cloud-storage.test.ts" },
   {
     source: "src/commands/doctor/shared/channel-plugin-blockers.ts",
     test: "src/commands/doctor/shared/channel-plugin-blockers.test.ts",

Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,7 @@ const commandsLightEntries = [`
`14`	`14`	`source: "src/commands/doctor-gateway-auth-token.ts",`
`15`	`15`	`test: "src/commands/doctor-gateway-auth-token.test.ts",`
`16`	`16`	`},`
	`17`	`+ { test: "src/commands/doctor-state-integrity.cloud-storage.test.ts" },`
`17`	`18`	`{`
`18`	`19`	`source: "src/commands/doctor/shared/channel-plugin-blockers.ts",`
`19`	`20`	`test: "src/commands/doctor/shared/channel-plugin-blockers.test.ts",`