PR #56810: Onboard: persist default workspace as portable ~/.openclaw path

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

Description (problem / solution / changelog)

Summary

Describe the problem and fix in 2–5 bullets:

• Problem: onboarding/setup could persist resolved absolute default workspace paths in config, which can look like hardcoded host-specific paths when config is migrated/synced across machines.
• Why it matters: config portability suffers and users can see confusing foreign absolute paths.
• What changed: when workspace matches canonical default, config now stores portable ~/.openclaw/workspace (profile-aware) instead of absolute home path.
• What did NOT change (scope boundary): runtime filesystem operations still resolve to absolute paths at execution time.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #51429
• Related #
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: onboarding/configure/setup resolved default workspace to absolute path and wrote it directly to agents.defaults.workspace.
• Missing detection / guardrail: no canonical mapping back to portable default string for persisted config.
• Prior context (git blame, prior PR, issue, or refactor if known): issue #51429 reports apparent hardcoded path behavior from config baking.
• Why this regressed now: portability issues become visible when configs are reused across hosts.
• If unknown, what was ruled out: actual hardcoded username path in source was ruled out.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/workspace.defaults.test.ts, src/commands/setup.test.ts
• Scenario the test should lock in: default workspace persistence remains portable (~/.openclaw/...) while runtime still resolves absolute path correctly.
• Why this is the smallest reliable guardrail: bug is in config serialization for default workspace value.
• Existing test that already covers this (if any): setup/onboard tests extended for persisted value expectations.
• If no new test is added, why not: N/A.

User-visible / Behavior Changes

• Config files now store portable default workspace strings for default path cases.

Diagram (if applicable)

Before:
default workspace -> resolve absolute path -> persist /Users/<name>/.openclaw/workspace

After:
default workspace -> detect canonical default -> persist ~/.openclaw/workspace

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS (dev)
• Runtime/container: Node 24 / pnpm workspace
• Model/provider: N/A
• Integration/channel (if any): onboarding/setup/configure flows
• Relevant config (redacted): default workspace settings

Steps

1. Run setup/onboard/configure with default workspace value.
2. Inspect saved agents.defaults.workspace in config.
3. Confirm persisted value is portable ~/.openclaw/... and runtime still resolves correctly.

Expected

• Portable default path in config for canonical default workspace.

Actual

• Config now stores ~/.openclaw/workspace (or profile-specific variant) for default-path cases.

Evidence

• Failing test/log before + passing after

• Trace/log snippets

• Screenshot/recording

• Perf numbers (if relevant)

• pnpm test -- src/agents/workspace.defaults.test.ts src/commands/setup.test.ts src/commands/onboard-config.test.ts

• pnpm test -- src/wizard/setup.test.ts

Human Verification (required)

• Verified scenarios: setup/onboard/configure persist portable defaults when using canonical workspace.
• Edge cases checked: profile-aware default workspace suffix behavior.
• What you did not verify: full interactive onboarding matrix across all shells/platforms manually.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: users relying on absolute default path serialization may notice config text changes.
  • Mitigation: runtime path resolution remains unchanged; only persisted default representation becomes portable.

Made with Cursor

Changed files

• src/agents/workspace.defaults.test.ts (modified, +29/-1)
• src/agents/workspace.ts (modified, +29/-0)
• src/commands/configure.wizard.ts (modified, +2/-1)
• src/commands/onboard-helpers.ts (modified, +2/-2)
• src/commands/onboard-non-interactive/local.ts (modified, +5/-1)
• src/commands/setup.test.ts (modified, +1/-0)
• src/commands/setup.ts (modified, +15/-3)
• src/wizard/setup.ts (modified, +5/-1)