Skip to content

docs(openclaw): document split roots and host-path remap defaults#2

Closed
kalinon wants to merge 6 commits intoByMosDev:mainfrom
moltar-forge:codex/feature-openclaw-split-roots-docs
Closed

docs(openclaw): document split roots and host-path remap defaults#2
kalinon wants to merge 6 commits intoByMosDev:mainfrom
moltar-forge:codex/feature-openclaw-split-roots-docs

Conversation

@kalinon
Copy link
Copy Markdown
Contributor

@kalinon kalinon commented Mar 3, 2026

Summary

This PR updates OpenClaw documentation to match Path Law v2:

  • single mounted config root
  • main workspace as subdirectory
  • canonical main virtual path /
  • no /workspace alias

Changes

  • Updated setup and deployment guidance to use:
    • CONFIG_ROOT=/openclaw-config
    • MAIN_WORKSPACE_DIR=workspace
    • single mount (~/.openclaw:/openclaw-config)
  • Updated workspace-service reference docs:
    • filesystem layout and virtual path mapping
    • endpoint table corrections
    • troubleshooting language for CONFIG_ROOT
  • Updated troubleshooting with explicit legacy-alias guidance:
    • PATH_NOT_ALLOWED when using /workspace/...
    • use / for main, /workspace-<agent> for sub-agents, /projects|/skills|/docs for shared
  • Added virtual path conventions to getting-started configuration docs

Issues Solved

  • Confusion around split mounts and compounded workspace pathing
  • Misunderstanding of where main workspace should resolve
  • Missing guidance for deprecated /workspace virtual alias behavior

Related PRs

Tracking issue:

kalinon added 3 commits March 3, 2026 10:00
Document the correct OpenClaw home mount pattern, explicitly set WORKSPACE_SUBDIR=. to avoid /workspace/workspace nesting, and clarify that normal MosBot usage requires read-write workspace mounts.
Update setup, workspace-service, troubleshooting, and configuration docs to use WORKSPACE_FS_ROOT + CONFIG_FS_ROOT, document migration from WORKSPACE_ROOT/WORKSPACE_SUBDIR, and add remap-prefix troubleshooting guidance.
Update OpenClaw configuration and troubleshooting docs to include both default remap prefixes: /home/node/.openclaw and ~/.openclaw. This matches API defaults and clarifies how host-absolute paths are translated into virtual workspace paths.
kalinon added 2 commits March 3, 2026 15:23
Clarify that OPENCLAW_PATH_REMAP_PREFIXES appends custom prefixes while built-in prefixes are always active, and document that the most specific prefix wins when multiple remap prefixes match.
@kalinon
Copy link
Copy Markdown
Contributor Author

kalinon commented Mar 3, 2026

Follow-up docs update for Path Law v2.

New commit: c0d7ebe

Highlights:

  • setup/workspace-service/troubleshooting docs now use CONFIG_ROOT + MAIN_WORKSPACE_DIR
  • single-mount examples (~/.openclaw:/openclaw-config)
  • explicit guidance for canonical virtual paths and /workspace alias removal
  • added virtual path conventions to getting-started configuration docs

- update setup/workspace-service docs to map main workspace to /workspace\n- align troubleshooting guidance and examples with /workspace/* requests\n- update configuration reference virtual path conventions
@kalinon
Copy link
Copy Markdown
Contributor Author

kalinon commented Mar 6, 2026

Superseded by #4 (#4), which rolls up all commits currently on moltar-forge:main relative to bymosbot:main.

@kalinon kalinon closed this Mar 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant