ByMosDev · kalinon · Mar 3, 2026 · Mar 3, 2026 · Mar 3, 2026 · Mar 3, 2026
diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md
@@ -74,6 +74,13 @@ variables, the workspace browser and skills features will be unavailable.
 | -------------------------- | ------- | ------------------------------------------------------------------------------------ |
 | `OPENCLAW_WORKSPACE_URL`   | —       | URL of the OpenClaw workspace service (e.g. `http://localhost:8080`)                 |
 | `OPENCLAW_WORKSPACE_TOKEN` | —       | Bearer token for workspace service authentication. Obtain from OpenClaw admin panel. |
+| `OPENCLAW_PATH_REMAP_PREFIXES` | `''` | Comma-separated additional host path prefixes remapped to virtual workspace paths before allowlist checks. Built-ins are always active: `/home/node/.openclaw/workspace`, `~/.openclaw/workspace`, `/home/node/.openclaw`, `~/.openclaw` (most specific prefix wins). |
+
+Virtual path conventions:
+
+- Main workspace: `/workspace`
+- Sub-agent workspaces: `/workspace-<agent-id>`
+- Shared directories: `/projects`, `/skills`, `/docs`
 
 ## OpenClaw Gateway
 

diff --git a/docs/openclaw/setup.md b/docs/openclaw/setup.md
@@ -33,31 +33,41 @@ next to your OpenClaw instance, sharing the same workspace directory or volume.
 ### Option A: Docker (local)
 
 Add the MosBot workspace service to the same Docker Compose file as OpenClaw. It must share the same
-workspace volume:
+OpenClaw home directory volume:
 
 ```yaml
 services:
   openclaw:
     image: openclaw/openclaw:latest
     volumes:
-      - openclaw-workspace:/home/user/.openclaw/workspace
+      - ~/.openclaw:/home/node/.openclaw
     ports:
       - '18789:18789'
 
   mosbot-workspace:
     image: ghcr.io/bymosbot/mosbot-workspace-service:latest
     environment:
       WORKSPACE_SERVICE_TOKEN: your-secure-token
-      WORKSPACE_ROOT: /workspace
+      CONFIG_ROOT: /openclaw-config
+      MAIN_WORKSPACE_DIR: workspace
     volumes:
-      - openclaw-workspace:/workspace:ro
+      - ~/.openclaw:/openclaw-config
     ports:
       - '8080:8080'
-
-volumes:
-  openclaw-workspace:
 ```
 
+:::info Path contract
+
+- `CONFIG_ROOT` is the single mounted OpenClaw root (typically `~/.openclaw`).
+- `MAIN_WORKSPACE_DIR` selects the main workspace subdirectory inside that root (default:
+  `workspace`).
+- Main workspace virtual path is `/workspace`.
+- Sub-agent workspaces resolve from `/workspace-<agent>` to `~/.openclaw/workspace-<agent>`.
+- Shared dirs `/projects`, `/skills`, `/docs` resolve to `~/.openclaw/{projects,skills,docs}`.
+- Use a read-write mount for normal MosBot usage (Projects/Skills/Docs and config edits).
+
+:::
+
 Once running, the services are available at:
 
 - Workspace service: `http://localhost:8080`
@@ -71,19 +81,26 @@ See [Kubernetes Deployment](./kubernetes) for the full guide with manifests.
 
 ### Option C: VPS / remote server
 
-Run the workspace service container on the same server as OpenClaw, mounting the same workspace
+Run the workspace service container on the same server as OpenClaw, mounting the same workspace home
 directory:
 
 ```bash
 docker run -d \
   --name mosbot-workspace \
   -e WORKSPACE_SERVICE_TOKEN=your-secure-token \
-  -e WORKSPACE_ROOT=/workspace \
-  -v /path/to/openclaw/workspace:/workspace:ro \
+  -e CONFIG_ROOT=/openclaw-config \
+  -e MAIN_WORKSPACE_DIR=workspace \
+  -v /path/to/openclaw/config:/openclaw-config \
   -p 8080:8080 \
   ghcr.io/bymosbot/mosbot-workspace-service:latest
 ```
 
+## Migration from old workspace env model
+
+- Old: `WORKSPACE_FS_ROOT` + `CONFIG_FS_ROOT`
+- New: `CONFIG_ROOT` + `MAIN_WORKSPACE_DIR`
+- Old variables are no longer honored.
+
 :::warning Security Note
 
 Do not expose port 8080 to the public internet. Use a VPN or private network, and always use a

diff --git a/docs/openclaw/troubleshooting.md b/docs/openclaw/troubleshooting.md
@@ -50,6 +50,21 @@ curl http://localhost:18789/health
 
 ---
 
+### Workspace status returns root path errors
+
+**Cause**: `CONFIG_ROOT` and/or `MAIN_WORKSPACE_DIR` are misconfigured, or the mounted
+`CONFIG_ROOT` path is missing.
+
+**Fix**:
+
+1. Set `CONFIG_ROOT` to the OpenClaw root mount (for example `/openclaw-config`)
+2. Set `MAIN_WORKSPACE_DIR` to the main workspace folder name (for example `workspace`)
+3. Verify `CONFIG_ROOT` exists and is readable by the workspace service container
+4. Verify `${CONFIG_ROOT}/${MAIN_WORKSPACE_DIR}` exists for main workspace access
+5. Use a read-write mount for normal dashboard usage (Projects/Skills/Docs and config editing)
+
+---
+
 ### 401 Unauthorized on OpenClaw endpoints
 
 **Cause**: The bearer token in MosBot's `.env` doesn't match the token configured in OpenClaw.
@@ -99,6 +114,63 @@ curl -H "Authorization: Bearer <mosbot-jwt>" \
 
 ---
 
+### Workspace loads, but models/agents fail
+
+**Cause**: `CONFIG_ROOT` is not mounted correctly, so
+`/openclaw.json` cannot be read.
+
+**Fix**:
+
+1. Verify workspace service env includes `CONFIG_ROOT`
+2. Verify config mount contains `openclaw.json` and `org-chart.json`
+3. Test directly:
+   ```bash
+   curl -H "Authorization: Bearer <workspace-token>" \
+     "http://localhost:8080/files/content?path=/openclaw.json"
+   ```
+
+---
+
+### Config edits fail, but file browsing works
+
+**Cause**: `CONFIG_ROOT` is mounted read-only or points to the wrong directory.
+
+**Fix**:
+
+1. Mount config path read-write
+2. Confirm container user has write permission
+3. Retry editing `openclaw.json` or `org-chart.json` from the dashboard
+
+---
+
+### Path remap errors (`PATH_NOT_ALLOWED`) for host-absolute paths
+
+**Cause**: `OPENCLAW_PATH_REMAP_PREFIXES` does not match the absolute path prefix returned by your
+OpenClaw agent config.
+
+**Fix**:
+
+1. Set `OPENCLAW_PATH_REMAP_PREFIXES` in MosBot API (this env var appends custom prefixes)
+2. Built-in prefixes are always active: `/home/node/.openclaw/workspace`, `~/.openclaw/workspace`, `/home/node/.openclaw`, `~/.openclaw`
+3. Most specific prefix wins when multiple prefixes match
+4. Add any extra custom prefixes via `OPENCLAW_PATH_REMAP_PREFIXES`, comma-separated
+5. Restart MosBot API
+
+---
+
+### `PATH_NOT_ALLOWED` for main workspace files
+
+**Cause**: Main workspace paths must use the canonical `/workspace` namespace.
+
+**Fix**:
+
+1. Use `/workspace` for main workspace root
+2. Use `/workspace/<path>` for files under main workspace (not `/<path>`)
+3. Use `/workspace-<agent>` for sub-agent workspaces
+4. Use `/projects`, `/skills`, `/docs` for shared directories
+
+---
+
 ### Port-forward keeps dropping (Kubernetes)
 
 **Cause**: The OpenClaw pod restarted, or the port-forward connection timed out.
@@ -163,7 +235,7 @@ curl -H "Authorization: Bearer <mosbot-jwt>" \
 
 # List workspace files
 curl -H "Authorization: Bearer <mosbot-jwt>" \
-  "http://localhost:3000/api/v1/openclaw/workspace/files?path=/&recursive=false"
+  "http://localhost:3000/api/v1/openclaw/workspace/files?path=/workspace&recursive=false"
 
 # Check gateway sessions
 curl -H "Authorization: Bearer <mosbot-jwt>" \

diff --git a/docs/openclaw/workspace-service.md b/docs/openclaw/workspace-service.md
@@ -17,6 +17,18 @@ next to your OpenClaw instance. The image supports both `linux/amd64` and `linux
 
 See [Setting Up OpenClaw](./setup) for Docker and Kubernetes deployment examples. :::
 
+## Recommended mount configuration
+
+For full MosBot functionality (agent discovery + Projects/Skills/Docs file edits), use:
+
+- `CONFIG_ROOT=/openclaw-config`
+- `MAIN_WORKSPACE_DIR=workspace`
+- A single read-write mount for OpenClaw root (for example `~/.openclaw:/openclaw-config`)
+
+`openclaw.json`, `org-chart.json`, shared folders (`projects`, `skills`, `docs`), and sub-agent
+workspaces (`workspace-<agent>`) are resolved from `CONFIG_ROOT`. Main workspace virtual path
+`/workspace` resolves to `CONFIG_ROOT/MAIN_WORKSPACE_DIR`.
+
 ## What the workspace service provides
 
 - **File access**: read, create, update, and delete files in agent workspaces
@@ -35,8 +47,9 @@ OpenClaw Workspace Service (port 8080)
     │
     │ Filesystem access
     ▼
-Workspace PVC / directory
-(workspace-coo/, workspace-cto/, skills/, shared/, etc.)
+Workspace PVC / directories
+(`CONFIG_ROOT`: openclaw.json, org-chart.json, projects/, skills/, docs/, workspace-<agent>/...
+ `CONFIG_ROOT/MAIN_WORKSPACE_DIR`: main workspace for virtual path `/workspace`)
 ```
 
 In Kubernetes, the workspace service runs as a sidecar container in the OpenClaw pod and shares the
@@ -74,21 +87,25 @@ internet:
 
 ## Workspace directory structure
 
-A typical OpenClaw workspace layout:
+A typical OpenClaw layout:
 
 ```text
-/                           ← workspace root
-├── workspace-coo/          ← agent workspace (COO agent)
+/openclaw-config            ← CONFIG_ROOT
+├── openclaw.json           ← OpenClaw configuration
+├── org-chart.json          ← Org chart configuration
+├── workspace               ← main workspace (MAIN_WORKSPACE_DIR, virtual path "/workspace")
+│   ├── memory/
+│   └── HEARTBEAT.md
+├── workspace-coo/          ← sub-agent workspace (virtual path "/workspace-coo")
 │   ├── memory/             ← agent memory files
 │   ├── skills/             ← agent-specific skills
 │   └── HEARTBEAT.md        ← heartbeat context file
-├── workspace-cto/          ← agent workspace (CTO agent)
+├── workspace-cto/          ← sub-agent workspace (virtual path "/workspace-cto")
 │   ├── memory/
 │   └── skills/
-├── skills/                 ← shared skills (available to all agents)
-├── docs/                   ← shared documentation
-├── projects/               ← shared project files
-└── openclaw.json           ← OpenClaw configuration
+├── projects/               ← shared project files (virtual path "/projects")
+├── skills/                 ← shared skills (virtual path "/skills")
+└── docs/                   ← shared docs (virtual path "/docs")
 ```
 
 ## API endpoints (via MosBot API)
@@ -99,10 +116,10 @@ MosBot API proxies workspace requests through its own authenticated endpoints:
 | ---------------------------------------- | ---------------------------------------- |
 | `GET /api/v1/openclaw/workspace/status`  | Check workspace service connectivity     |
 | `GET /api/v1/openclaw/workspace/files`   | List files (params: `path`, `recursive`) |
-| `GET /api/v1/openclaw/workspace/file`    | Read a file (param: `path`)              |
-| `POST /api/v1/openclaw/workspace/file`   | Create a new file                        |
-| `PUT /api/v1/openclaw/workspace/file`    | Update an existing file                  |
-| `DELETE /api/v1/openclaw/workspace/file` | Delete a file                            |
+| `GET /api/v1/openclaw/workspace/files/content` | Read a file (param: `path`)        |
+| `POST /api/v1/openclaw/workspace/files`  | Create a new file                        |
+| `PUT /api/v1/openclaw/workspace/files`   | Update an existing file                  |
+| `DELETE /api/v1/openclaw/workspace/files` | Delete a file                           |
 | `GET /api/v1/openclaw/config`            | Read `openclaw.json`                     |
 | `PUT /api/v1/openclaw/config`            | Update `openclaw.json`                   |
 | `GET /api/v1/openclaw/agents`            | List agents from `openclaw.json`         |
@@ -130,5 +147,12 @@ curl -H "Authorization: Bearer <mosbot-jwt>" \
 **401 Unauthorized** The token doesn't match. Verify `OPENCLAW_WORKSPACE_TOKEN` in MosBot API's
 `.env` matches the token configured in the workspace service.
 
+**Workspace loads but models/agents fail**
+`CONFIG_ROOT` is not mounted correctly. Verify `/files/content?path=/openclaw.json` succeeds on
+the workspace service.
+
+**Config edits fail but file browsing works**
+`CONFIG_ROOT` is mounted read-only or points to the wrong directory.
+
 **Path traversal errors** The path contains `..` or other traversal sequences. Use absolute paths
 from the workspace root (e.g. `/workspace-coo/memory/2026-03-01.md`).