#13497: fix(docker): normalize workspace paths for container compatibility
cli
commands
agents
stale
Cluster:
Workspace Path Fixes
## Summary
Fixes `EACCES: permission denied, mkdir '/Users'` error when running `docker compose run --rm openclaw-cli onboard` in Docker containers.
## Problem
The existing `openclaw.json` (created on macOS host, mounted into container) stores absolute host paths like `workspace: /Users/cy/.openclaw/workspace`. Inside the container (`HOME=/home/node`, user `node` uid 1000), the onboarding tries to `mkdir` this macOS path, which fails because the `node` user cannot create `/Users` in the container root.
## Solution
Add `normalizeWorkspacePath()` utility that detects when a stored workspace path follows the `<HOME>/.openclaw/workspace` pattern but with a different HOME than the current environment, and remaps it to the current HOME.
## Changes
- Add `normalizeWorkspacePath()` in `workspace.ts`
- Apply normalization at all workspace config read sites:
- `onboarding.ts` (interactive wizard)
- `onboard.ts` (reset path)
- `workspace.ts` (non-interactive onboarding)
- `configure.wizard.ts` (configure command)
- Fix `completion-cli.ts` to use `resolveRequiredHomeDir()` instead of direct `process.env.HOME || os.homedir()` access
- Add comprehensive unit tests for path normalization edge cases
## Impact
- ✅ No config format change - zero migration needed
- ✅ No impact on non-Docker users (same HOME = path unchanged)
- ✅ Custom workspace paths preserved (only default-pattern paths remapped)
- ✅ Respects `OPENCLAW_HOME`, `HOME`, and `USERPROFILE` env vars
## Testing
- All existing tests pass
- New unit tests cover normalization edge cases (foreign HOME, profiles, custom paths, env var precedence)
<!-- greptile_comment -->
<h2>Greptile Overview</h2>
<h3>Greptile Summary</h3>
This PR addresses a Docker onboarding failure where a host-generated `openclaw.json` can contain an absolute workspace path (e.g. macOS `/Users/...`) that isn’t writable inside the container. It introduces `normalizeWorkspacePath()` (in `src/agents/workspace.ts`) and applies it when reading stored workspace paths in the onboarding/configure flows (`src/wizard/onboarding.ts`, `src/commands/onboard.ts`, `src/commands/onboard-non-interactive/local/workspace.ts`, `src/commands/configure.wizard.ts`). It also updates completion install logic to use the centralized home-directory resolver (`src/cli/completion-cli.ts`) and adds unit tests covering normalization behavior.
Key integration point: the normalization is applied at config read sites before `resolveUserPath()` and before workspace/session initialization, aiming to keep config portable across environments while preserving truly custom workspace paths.
<h3>Confidence Score: 3/5</h3>
- This PR is close, but has a couple of merge-blocking issues that can break user configs or leak local tooling config into the repo.
- The overall approach is reasonable and tests were added, but (1) a local Claude settings file was committed and should not ship, and (2) `normalizeWorkspacePath()` currently matches the normalization suffix anywhere in the path, which can incorrectly rewrite custom workspace paths that contain `/.openclaw/workspace` as a subpath. Fixing those should make the PR safe to merge.
- src/agents/workspace.ts, .claude/settings.local.json
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#11529: fix(wizard): strip shell-style backslash escapes from workspace paths
by mcaxtr · 2026-02-07
81.8%
#23085: fix(workspace): respect OPENCLAW_STATE_DIR for workspace paths, fix...
by charojo · 2026-02-22
80.8%
#11333: fix(docker): align host directory ownership with container user
by liuxiaopai-ai · 2026-02-07
79.1%
#2884: fix: Create memory directory and symlink identity files during work...
by webdevtodayjason · 2026-01-27
77.0%
#3513: fix(docker): add MOLTBOT_STATE_DIR to resolve permission error
by Suksham-sharma · 2026-01-28
76.9%
#13873: fix(sandbox): prevent Windows PATH from poisoning docker exec
by alessandrorodi · 2026-02-11
76.7%
#17757: fix(agents): resolve relative workspace paths against state dir, no...
by Phineas1500 · 2026-02-16
76.6%
#9999: Docker: fix token mismatch and add dev setup workflow
by benclarkeio · 2026-02-06
76.0%
#11820: fix(sandbox): remap container paths in sandboxed file tools
by steflsd · 2026-02-08
76.0%
#7133: feat: Automated Docker setup with environment-based configuration
by synetalsolutions · 2026-02-02
75.9%