PR #63595: fix(workspace): surface cross-OS migration hint on ENOENT mkdir failure

• Repository: openclaw/openclaw
• Author: hclsys
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63595

Description (problem / solution / changelog)

Summary

When users migrate an OpenClaw state directory between Linux/WSL and macOS (or vice versa), openclaw.json still references absolute workspace paths from the original host — commonly /home/<user>/.openclaw/workspace on a host where home is actually /Users/<user>.

ensureAgentWorkspace() calls fs.mkdir(dir, { recursive: true }) on the stale path and fails with a raw ENOENT: no such file or directory, mkdir '/home/<user>' in the gateway error log, because /home is not a writable location for non-root users on macOS. Agents silently fail on every inbound message with no visible hint that the root cause is a stale absolute path in config.

Fixes #63572

Reporter's stack trace (from #63572)

error gateway/channels/telegram telegram bot error:
  Error: ENOENT: no such file or directory, mkdir '/home/<username>'
    at Object.mkdir (node:internal/fs/promises:852:10)
    at ensureAgentWorkspace (workspace-Q6iYWMyk.js:256:2)
    at getReplyFromConfig (reply-DW8PLbAC.js:3079:130)
    at dispatchReplyFromConfig (dispatch-BvwlsDx2.js:590:23)
    ...

The dist/workspace-Q6iYWMyk.js:256 line corresponds to src/agents/workspace.ts:340 — the fs.mkdir(dir, { recursive: true }) call inside ensureAgentWorkspace.

Fix

Catch ENOENT from the initial mkdir and, if the path pattern looks like a cross-OS home-prefix mismatch (/home/<user> on a host with /Users/... home, or vice versa), throw a new Error that explicitly names:

1. The failing path
2. The current host's home
3. The exact config key (agents.defaults.workspace) the user must update
4. The alternative (openclaw setup to reset)

The original error is preserved as cause for debugging. Non-cross-OS ENOENTs still surface the original error unchanged, so unrelated permission/filesystem failures are not masked.

The detection logic is extracted into an exported pure function buildCrossOsWorkspaceMigrationHint(dir, home) so the behaviour can be unit-tested without touching the real filesystem.

Why error-message, not auto-rewrite

An earlier option considered was to silently rewrite the stale path to the current user's home. Rejected because:

• Could corrupt intentional cross-user or shared workspace setups
• Silent mutation of config files is a trust violation
• A clear, actionable error lets the user decide: update the path, reset via openclaw setup, or symlink the directory

Tests

Added describe(\"buildCrossOsWorkspaceMigrationHint (#63572)\") block with 6 cases in src/agents/workspace.test.ts:

1. Linux home prefix on macOS host → hint emitted, mentions /home/alice, "macOS", and agents.defaults.workspace
2. macOS home prefix on Linux host → hint emitted, mentions /Users/bob, "Linux", and agents.defaults.workspace
3. Workspace already under current home → null (no false-positive on happy path)
4. Bespoke workspace outside any home tree (e.g. /srv/shared/..., /opt/...) → null (not a migration issue)
5. Empty inputs → null (defensive)
6. Same-OS different-user shared workspace → null (could be intentional, avoid misleading hint)

Scope

• 2 files touched, +122 / -1
• One new exported helper (buildCrossOsWorkspaceMigrationHint) for testability
• One new try/catch around the existing fs.mkdir call
• Zero changes to the happy path (workspace creation succeeds unchanged)
• Zero changes to the ensureBootstrapFiles logic downstream of mkdir

Credit to @davidperjac for the detailed repro and full stack trace in the issue.

Changed files

• src/agents/workspace.test.ts (modified, +58/-0)
• src/agents/workspace.ts (modified, +64/-1)

PR #63803: fix(doctor): detect stale cross-OS workspace paths (#63572)

• Repository: openclaw/openclaw
• Author: vedantagarwal-web
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63803

Description (problem / solution / changelog)

Summary

Closes #63572.

When a user migrates their ~/.openclaw state directory across OSes (WSL/Linux → macOS, for example), any absolute paths persisted in openclaw.json for agents.defaults.workspace or per-agent workspace fields break silently. ensureAgentWorkspace later tries to mkdir -p the stale Linux path on a macOS host and fails with ENOENT, taking down every channel's agent dispatch with only gateway-log evidence.

This PR adds a new doctor health contribution — doctor:workspace-stale-paths — that detects these stale paths and offers to rewrite them to ~-relative form, which is durable across future migrations.

What changed

• New: src/commands/doctor-workspace-paths.ts — pure detectStaleWorkspacePaths(cfg, env) detector plus an effectful maybeRepairStaleWorkspacePaths(cfg, prompter, options) wrapper that matches the existing maybeRepairX pattern used elsewhere in doctor.
• New: src/commands/doctor-workspace-paths.test.ts — 14 unit tests covering: empty config, tilde passthrough, relative paths, existing-absolute passthrough, Linux→macOS, macOS→Linux, Windows→macOS, different-user same-OS, /root for non-root users, non-home absolute as missing-nonhome, nested subpath preservation, bare home root → ~, mixed healthy + stale agent list, and local-missing-same-home skip.
• Modified: src/flows/doctor-health-contributions.ts — register the new contribution immediately after doctor:workspace-status so mutations land before doctor:write-config persists.
• Modified: docs/install/migrating.md — new "Cross-OS absolute workspace paths" accordion under Common Pitfalls pointing at the new check.
• Modified: CHANGELOG.md — one line at the end of Unreleased > ### Fixes.

Detection rules

Home-shaped paths are inspected regardless of the current platform — a Windows-shaped path encountered on a macOS host is exactly the cross-OS case we want to catch.

Behavior

• Interactive mode: single confirmation prompt listing all stale paths and their proposed rewrites. On yes, mutates ctx.cfg; the existing doctor:write-config contribution persists the result on the same pass.
• Non-interactive mode (openclaw doctor --non-interactive): logs findings and manual-fix instructions, does not mutate.

Scope boundaries (explicitly out of scope)

• Does not touch gateway.staticDir, sandbox.workspaceRoot, or any other absolute-path config field. The reporter named only the agent workspace fields and expanding scope risks rewriting intentionally-absolute mounts.
• Does not change ensureAgentWorkspace or resolveAgentWorkspaceDir. Strict diagnose-and-repair at the doctor layer, matching the CLAUDE.md guidance ("for legacy config specifically, prefer doctor-owned repair paths over startup/load-time core migrations").
• Does not rewrite the migration guide — single accordion addition only.

Why ~ rather than absolute homedir

The reporter's failure mode is "stale absolute path after migration". Rewriting to another absolute path (for example the current /Users/me/...) just pushes the problem to the next migration. Writing ~/.openclaw/... keeps the config portable.

Test plan

• pnpm test src/commands/doctor-workspace-paths.test.ts — 14/14 passing
• pnpm test src/commands/doctor — 116/116 passing across 24 test files in the broader doctor suite, no regressions
• pnpm format — clean (no formatting churn in touched files)
• pnpm lint scoped to touched files (src/commands/doctor-workspace-paths*.ts and src/flows/doctor-health-contributions.ts) — 0 errors, 0 warnings
• Pre-commit hook fast lane (FAST_COMMIT=1) — clean
• Manual verification with a synthetic openclaw.json containing /home/<alt-user>/.openclaw/workspace on a macOS host — happy to do in a follow-up if a reviewer wants a live trace

Note on pnpm check

The full pnpm check gate halts on a pre-existing unrelated tsgo error in src/auto-reply/reply/followup-runner.test.ts:1140 (type cast from a literal config shape to OpenClawConfig rejected by the current CliBackendConfig index signature). I verified the error is present on origin/main with no changes applied, so it does not belong to this PR. My touched files type-check cleanly in isolation. Happy to adjust if a maintainer would prefer the check-gate-green requirement blocks landing here.

Co-Authored-By: Oz [email protected]

Changed files

• CHANGELOG.md (modified, +1/-0)
• docs/install/migrating.md (modified, +4/-0)
• src/commands/doctor-workspace-paths.test.ts (added, +172/-0)
• src/commands/doctor-workspace-paths.ts (added, +312/-0)
• src/flows/doctor-health-contributions.ts (modified, +12/-0)