From 296dce690412e183d9b65b9e69614854ed6c4db8 Mon Sep 17 00:00:00 2001 From: Holden Omans Date: Tue, 3 Mar 2026 10:00:25 -0500 Subject: [PATCH 1/6] docs(openclaw): fix workspace sidecar mount and subdir guidance 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. --- docs/openclaw/setup.md | 25 +++++++++++++++++++------ docs/openclaw/troubleshooting.md | 13 +++++++++++++ docs/openclaw/workspace-service.md | 11 +++++++++++ 3 files changed, 43 insertions(+), 6 deletions(-) diff --git a/docs/openclaw/setup.md b/docs/openclaw/setup.md index d0b3a6e..f18430c 100644 --- a/docs/openclaw/setup.md +++ b/docs/openclaw/setup.md @@ -33,14 +33,14 @@ 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:/home/node/.openclaw ports: - '18789:18789' @@ -49,15 +49,27 @@ services: environment: WORKSPACE_SERVICE_TOKEN: your-secure-token WORKSPACE_ROOT: /workspace + WORKSPACE_SUBDIR: . volumes: - - openclaw-workspace:/workspace:ro + - openclaw-home:/workspace ports: - '8080:8080' volumes: - openclaw-workspace: + openclaw-home: ``` +:::info Why this mount shape? + +- Mount `~/.openclaw` (not only `~/.openclaw/workspace`) so the workspace service can access both + workspace files and `openclaw.json`. +- `WORKSPACE_SUBDIR: .` exposes the mounted root directly and avoids accidental + `/workspace/workspace` path nesting. +- Use read-write mounts for normal MosBot usage (Projects/Skills/Docs pages create and edit files). + Read-only mounts are only suitable for status/read-only troubleshooting. + +::: + Once running, the services are available at: - Workspace service: `http://localhost:8080` @@ -71,7 +83,7 @@ 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 @@ -79,7 +91,8 @@ 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 WORKSPACE_SUBDIR=. \ + -v /path/to/.openclaw:/workspace \ -p 8080:8080 \ ghcr.io/bymosbot/mosbot-workspace-service:latest ``` diff --git a/docs/openclaw/troubleshooting.md b/docs/openclaw/troubleshooting.md index 5c0b488..b1079e7 100644 --- a/docs/openclaw/troubleshooting.md +++ b/docs/openclaw/troubleshooting.md @@ -50,6 +50,19 @@ curl http://localhost:18789/health --- +### Workspace status returns `ENOENT ... /workspace/workspace` + +**Cause**: `WORKSPACE_SUBDIR` is effectively set to `workspace` while your volume is already mounted +at the workspace directory. This creates an unintended nested lookup (`/workspace/workspace`). + +**Fix**: + +1. Mount OpenClaw home (`~/.openclaw`) to the container (for example `/workspace`) +2. Set `WORKSPACE_SUBDIR=.` on the workspace service +3. Use a read-write mount for normal dashboard usage (Projects/Skills/Docs and file creation) + +--- + ### 401 Unauthorized on OpenClaw endpoints **Cause**: The bearer token in MosBot's `.env` doesn't match the token configured in OpenClaw. diff --git a/docs/openclaw/workspace-service.md b/docs/openclaw/workspace-service.md index 07bb2b3..9ef0a72 100644 --- a/docs/openclaw/workspace-service.md +++ b/docs/openclaw/workspace-service.md @@ -17,6 +17,17 @@ 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: + +- `WORKSPACE_ROOT=/workspace` +- `WORKSPACE_SUBDIR=.` +- A read-write mount of your OpenClaw home directory (for example `~/.openclaw:/workspace`) + +This avoids accidental `/workspace/workspace` nesting and ensures `openclaw.json` is visible to the +workspace service. + ## What the workspace service provides - **File access**: read, create, update, and delete files in agent workspaces From cbe70819f4431d1612184050764b25fabb2b1680 Mon Sep 17 00:00:00 2001 From: Holden Omans Date: Tue, 3 Mar 2026 12:55:19 -0500 Subject: [PATCH 2/6] docs(openclaw): migrate to split root env model 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. --- docs/getting-started/configuration.md | 1 + docs/openclaw/setup.md | 36 ++++++++++-------- docs/openclaw/troubleshooting.md | 54 ++++++++++++++++++++++++--- docs/openclaw/workspace-service.md | 34 +++++++++++------ 4 files changed, 92 insertions(+), 33 deletions(-) diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index bb4096d..8841169 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -74,6 +74,7 @@ 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` | `/home/node/.openclaw` | Comma-separated host path prefixes remapped to virtual workspace paths before allowlist checks. | ## OpenClaw Gateway diff --git a/docs/openclaw/setup.md b/docs/openclaw/setup.md index f18430c..86dac3f 100644 --- a/docs/openclaw/setup.md +++ b/docs/openclaw/setup.md @@ -40,7 +40,7 @@ services: openclaw: image: openclaw/openclaw:latest volumes: - - openclaw-home:/home/node/.openclaw + - ~/.openclaw:/home/node/.openclaw ports: - '18789:18789' @@ -48,25 +48,22 @@ services: image: ghcr.io/bymosbot/mosbot-workspace-service:latest environment: WORKSPACE_SERVICE_TOKEN: your-secure-token - WORKSPACE_ROOT: /workspace - WORKSPACE_SUBDIR: . + WORKSPACE_FS_ROOT: /workspace + CONFIG_FS_ROOT: /openclaw-config volumes: - - openclaw-home:/workspace + - ~/.openclaw/workspace:/workspace + - ~/.openclaw:/openclaw-config ports: - '8080:8080' - -volumes: - openclaw-home: ``` :::info Why this mount shape? -- Mount `~/.openclaw` (not only `~/.openclaw/workspace`) so the workspace service can access both - workspace files and `openclaw.json`. -- `WORKSPACE_SUBDIR: .` exposes the mounted root directly and avoids accidental - `/workspace/workspace` path nesting. -- Use read-write mounts for normal MosBot usage (Projects/Skills/Docs pages create and edit files). - Read-only mounts are only suitable for status/read-only troubleshooting. +- `WORKSPACE_FS_ROOT` and `CONFIG_FS_ROOT` are independent, so OpenClaw config and workspace paths + can be configured separately. +- Config files (`openclaw.json`, `org-chart.json`) are always loaded from `CONFIG_FS_ROOT`. +- Use read-write mounts for normal MosBot usage (Projects/Skills/Docs plus config edits). + Read-only mounts are only suitable for read-only troubleshooting. ::: @@ -90,13 +87,20 @@ directory: docker run -d \ --name mosbot-workspace \ -e WORKSPACE_SERVICE_TOKEN=your-secure-token \ - -e WORKSPACE_ROOT=/workspace \ - -e WORKSPACE_SUBDIR=. \ - -v /path/to/.openclaw:/workspace \ + -e WORKSPACE_FS_ROOT=/workspace \ + -e CONFIG_FS_ROOT=/openclaw-config \ + -v /path/to/openclaw/workspace:/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_ROOT` + `WORKSPACE_SUBDIR` +- New: `WORKSPACE_FS_ROOT` + `CONFIG_FS_ROOT` +- 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 index b1079e7..4366c59 100644 --- a/docs/openclaw/troubleshooting.md +++ b/docs/openclaw/troubleshooting.md @@ -50,16 +50,16 @@ curl http://localhost:18789/health --- -### Workspace status returns `ENOENT ... /workspace/workspace` +### Workspace status returns root path errors -**Cause**: `WORKSPACE_SUBDIR` is effectively set to `workspace` while your volume is already mounted -at the workspace directory. This creates an unintended nested lookup (`/workspace/workspace`). +**Cause**: `WORKSPACE_FS_ROOT` and/or `CONFIG_FS_ROOT` do not point to mounted directories. **Fix**: -1. Mount OpenClaw home (`~/.openclaw`) to the container (for example `/workspace`) -2. Set `WORKSPACE_SUBDIR=.` on the workspace service -3. Use a read-write mount for normal dashboard usage (Projects/Skills/Docs and file creation) +1. Set `WORKSPACE_FS_ROOT` to the workspace mount (for example `/workspace`) +2. Set `CONFIG_FS_ROOT` to the config mount (for example `/openclaw-config`) +3. Verify both mounts exist and are readable by the workspace service container +4. Use read-write mounts for normal dashboard usage (Projects/Skills/Docs and config editing) --- @@ -112,6 +112,48 @@ curl -H "Authorization: Bearer " \ --- +### Workspace loads, but models/agents fail + +**Cause**: Workspace root is mounted, but config root is not mounted correctly, so +`/openclaw.json` cannot be read. + +**Fix**: + +1. Verify workspace service env includes `CONFIG_FS_ROOT` +2. Verify config mount contains `openclaw.json` and `org-chart.json` +3. Test directly: + ```bash + curl -H "Authorization: Bearer " \ + "http://localhost:8080/files/content?path=/openclaw.json" + ``` + +--- + +### Config edits fail, but file browsing works + +**Cause**: `CONFIG_FS_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 (default: `/home/node/.openclaw`) +2. Include every prefix you expect, comma-separated if needed +3. Restart MosBot API + +--- + ### Port-forward keeps dropping (Kubernetes) **Cause**: The OpenClaw pod restarted, or the port-forward connection timed out. diff --git a/docs/openclaw/workspace-service.md b/docs/openclaw/workspace-service.md index 9ef0a72..b29ddbc 100644 --- a/docs/openclaw/workspace-service.md +++ b/docs/openclaw/workspace-service.md @@ -21,12 +21,13 @@ See [Setting Up OpenClaw](./setup) for Docker and Kubernetes deployment examples For full MosBot functionality (agent discovery + Projects/Skills/Docs file edits), use: -- `WORKSPACE_ROOT=/workspace` -- `WORKSPACE_SUBDIR=.` -- A read-write mount of your OpenClaw home directory (for example `~/.openclaw:/workspace`) +- `WORKSPACE_FS_ROOT=/workspace` +- `CONFIG_FS_ROOT=/openclaw-config` +- A read-write mount for workspace files (for example `~/.openclaw/workspace:/workspace`) +- A read-write mount for OpenClaw config files (for example `~/.openclaw:/openclaw-config`) -This avoids accidental `/workspace/workspace` nesting and ensures `openclaw.json` is visible to the -workspace service. +`openclaw.json` and `org-chart.json` are always resolved from `CONFIG_FS_ROOT`. All other paths are +resolved from `WORKSPACE_FS_ROOT`. ## What the workspace service provides @@ -46,8 +47,9 @@ OpenClaw Workspace Service (port 8080) │ │ Filesystem access ▼ -Workspace PVC / directory -(workspace-coo/, workspace-cto/, skills/, shared/, etc.) +Workspace PVC / directories +(`WORKSPACE_FS_ROOT`: workspace-coo/, workspace-cto/, skills/, docs/, projects/, etc. + `CONFIG_FS_ROOT`: openclaw.json, org-chart.json) ``` In Kubernetes, the workspace service runs as a sidecar container in the OpenClaw pod and shares the @@ -85,10 +87,10 @@ internet: ## Workspace directory structure -A typical OpenClaw workspace layout: +A typical OpenClaw split-root layout: ```text -/ ← workspace root +/workspace ← WORKSPACE_FS_ROOT ├── workspace-coo/ ← agent workspace (COO agent) │ ├── memory/ ← agent memory files │ ├── skills/ ← agent-specific skills @@ -98,8 +100,11 @@ A typical OpenClaw workspace layout: │ └── skills/ ├── skills/ ← shared skills (available to all agents) ├── docs/ ← shared documentation -├── projects/ ← shared project files -└── openclaw.json ← OpenClaw configuration +└── projects/ ← shared project files + +/openclaw-config ← CONFIG_FS_ROOT +├── openclaw.json ← OpenClaw configuration +└── org-chart.json ← Org chart configuration ``` ## API endpoints (via MosBot API) @@ -141,5 +146,12 @@ curl -H "Authorization: Bearer " \ **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_FS_ROOT` is not mounted correctly. Verify `/files/content?path=/openclaw.json` succeeds on +the workspace service. + +**Config edits fail but file browsing works** +`CONFIG_FS_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`). From 28ef57f738685600983afad4f2e59844c1c5f63d Mon Sep 17 00:00:00 2001 From: Holden Omans Date: Tue, 3 Mar 2026 13:58:40 -0500 Subject: [PATCH 3/6] docs(openclaw): document ~/.openclaw remap prefix default 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. --- docs/getting-started/configuration.md | 2 +- docs/openclaw/troubleshooting.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index 8841169..83416c8 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -74,7 +74,7 @@ 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` | `/home/node/.openclaw` | Comma-separated host path prefixes remapped to virtual workspace paths before allowlist checks. | +| `OPENCLAW_PATH_REMAP_PREFIXES` | `/home/node/.openclaw,~/.openclaw` | Comma-separated host path prefixes remapped to virtual workspace paths before allowlist checks. | ## OpenClaw Gateway diff --git a/docs/openclaw/troubleshooting.md b/docs/openclaw/troubleshooting.md index 4366c59..2b35b93 100644 --- a/docs/openclaw/troubleshooting.md +++ b/docs/openclaw/troubleshooting.md @@ -148,7 +148,7 @@ OpenClaw agent config. **Fix**: -1. Set `OPENCLAW_PATH_REMAP_PREFIXES` in MosBot API (default: `/home/node/.openclaw`) +1. Set `OPENCLAW_PATH_REMAP_PREFIXES` in MosBot API (default: `/home/node/.openclaw,~/.openclaw`) 2. Include every prefix you expect, comma-separated if needed 3. Restart MosBot API From b04255556e0476991855010363e57e1a379f762c Mon Sep 17 00:00:00 2001 From: Holden Omans Date: Tue, 3 Mar 2026 15:23:34 -0500 Subject: [PATCH 4/6] docs(openclaw): document additive remap prefixes and precedence 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. --- docs/getting-started/configuration.md | 2 +- docs/openclaw/troubleshooting.md | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index 83416c8..54c18a3 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -74,7 +74,7 @@ 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` | `/home/node/.openclaw,~/.openclaw` | Comma-separated host path prefixes remapped to virtual workspace paths before allowlist checks. | +| `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). | ## OpenClaw Gateway diff --git a/docs/openclaw/troubleshooting.md b/docs/openclaw/troubleshooting.md index 2b35b93..50890a5 100644 --- a/docs/openclaw/troubleshooting.md +++ b/docs/openclaw/troubleshooting.md @@ -148,9 +148,11 @@ OpenClaw agent config. **Fix**: -1. Set `OPENCLAW_PATH_REMAP_PREFIXES` in MosBot API (default: `/home/node/.openclaw,~/.openclaw`) -2. Include every prefix you expect, comma-separated if needed -3. Restart MosBot API +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 --- From c0d7ebe5c4241520e2e33cbf6d1e22748b50c55d Mon Sep 17 00:00:00 2001 From: Holden Omans Date: Tue, 3 Mar 2026 16:37:11 -0500 Subject: [PATCH 5/6] docs(openclaw): document single config-root path contract --- docs/getting-started/configuration.md | 6 ++++ docs/openclaw/setup.md | 28 +++++++-------- docs/openclaw/troubleshooting.md | 30 +++++++++++----- docs/openclaw/workspace-service.md | 51 ++++++++++++++------------- 4 files changed, 68 insertions(+), 47 deletions(-) diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index 54c18a3..35244b4 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -76,6 +76,12 @@ variables, the workspace browser and skills features will be unavailable. | `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: `/` +- Sub-agent workspaces: `/workspace-` +- Shared directories: `/projects`, `/skills`, `/docs` + ## OpenClaw Gateway Required for agent monitoring, live session data, and runtime control. Without these variables, the diff --git a/docs/openclaw/setup.md b/docs/openclaw/setup.md index 86dac3f..af6245e 100644 --- a/docs/openclaw/setup.md +++ b/docs/openclaw/setup.md @@ -48,22 +48,23 @@ services: image: ghcr.io/bymosbot/mosbot-workspace-service:latest environment: WORKSPACE_SERVICE_TOKEN: your-secure-token - WORKSPACE_FS_ROOT: /workspace - CONFIG_FS_ROOT: /openclaw-config + CONFIG_ROOT: /openclaw-config + MAIN_WORKSPACE_DIR: workspace volumes: - - ~/.openclaw/workspace:/workspace - ~/.openclaw:/openclaw-config ports: - '8080:8080' ``` -:::info Why this mount shape? +:::info Path contract -- `WORKSPACE_FS_ROOT` and `CONFIG_FS_ROOT` are independent, so OpenClaw config and workspace paths - can be configured separately. -- Config files (`openclaw.json`, `org-chart.json`) are always loaded from `CONFIG_FS_ROOT`. -- Use read-write mounts for normal MosBot usage (Projects/Skills/Docs plus config edits). - Read-only mounts are only suitable for read-only troubleshooting. +- `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 `/` (no `/workspace` alias). +- Sub-agent workspaces resolve from `/workspace-` to `~/.openclaw/workspace-`. +- 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). ::: @@ -87,9 +88,8 @@ directory: docker run -d \ --name mosbot-workspace \ -e WORKSPACE_SERVICE_TOKEN=your-secure-token \ - -e WORKSPACE_FS_ROOT=/workspace \ - -e CONFIG_FS_ROOT=/openclaw-config \ - -v /path/to/openclaw/workspace:/workspace \ + -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 @@ -97,8 +97,8 @@ docker run -d \ ## Migration from old workspace env model -- Old: `WORKSPACE_ROOT` + `WORKSPACE_SUBDIR` -- New: `WORKSPACE_FS_ROOT` + `CONFIG_FS_ROOT` +- Old: `WORKSPACE_FS_ROOT` + `CONFIG_FS_ROOT` +- New: `CONFIG_ROOT` + `MAIN_WORKSPACE_DIR` - Old variables are no longer honored. :::warning Security Note diff --git a/docs/openclaw/troubleshooting.md b/docs/openclaw/troubleshooting.md index 50890a5..995d2d5 100644 --- a/docs/openclaw/troubleshooting.md +++ b/docs/openclaw/troubleshooting.md @@ -52,14 +52,16 @@ curl http://localhost:18789/health ### Workspace status returns root path errors -**Cause**: `WORKSPACE_FS_ROOT` and/or `CONFIG_FS_ROOT` do not point to mounted directories. +**Cause**: `CONFIG_ROOT` and/or `MAIN_WORKSPACE_DIR` are misconfigured, or the mounted +`CONFIG_ROOT` path is missing. **Fix**: -1. Set `WORKSPACE_FS_ROOT` to the workspace mount (for example `/workspace`) -2. Set `CONFIG_FS_ROOT` to the config mount (for example `/openclaw-config`) -3. Verify both mounts exist and are readable by the workspace service container -4. Use read-write mounts for normal dashboard usage (Projects/Skills/Docs and config editing) +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) --- @@ -114,12 +116,12 @@ curl -H "Authorization: Bearer " \ ### Workspace loads, but models/agents fail -**Cause**: Workspace root is mounted, but config root is not mounted correctly, so +**Cause**: `CONFIG_ROOT` is not mounted correctly, so `/openclaw.json` cannot be read. **Fix**: -1. Verify workspace service env includes `CONFIG_FS_ROOT` +1. Verify workspace service env includes `CONFIG_ROOT` 2. Verify config mount contains `openclaw.json` and `org-chart.json` 3. Test directly: ```bash @@ -131,7 +133,7 @@ curl -H "Authorization: Bearer " \ ### Config edits fail, but file browsing works -**Cause**: `CONFIG_FS_ROOT` is mounted read-only or points to the wrong directory. +**Cause**: `CONFIG_ROOT` is mounted read-only or points to the wrong directory. **Fix**: @@ -156,6 +158,18 @@ OpenClaw agent config. --- +### `PATH_NOT_ALLOWED` when using `/workspace/...` + +**Cause**: `/workspace` is no longer a valid virtual path alias for main workspace. + +**Fix**: + +1. Use `/` for main workspace root +2. Use `/workspace-` for sub-agent workspaces +3. Use `/projects`, `/skills`, `/docs` for shared directories + +--- + ### Port-forward keeps dropping (Kubernetes) **Cause**: The OpenClaw pod restarted, or the port-forward connection timed out. diff --git a/docs/openclaw/workspace-service.md b/docs/openclaw/workspace-service.md index b29ddbc..8656db8 100644 --- a/docs/openclaw/workspace-service.md +++ b/docs/openclaw/workspace-service.md @@ -21,13 +21,13 @@ See [Setting Up OpenClaw](./setup) for Docker and Kubernetes deployment examples For full MosBot functionality (agent discovery + Projects/Skills/Docs file edits), use: -- `WORKSPACE_FS_ROOT=/workspace` -- `CONFIG_FS_ROOT=/openclaw-config` -- A read-write mount for workspace files (for example `~/.openclaw/workspace:/workspace`) -- A read-write mount for OpenClaw config files (for example `~/.openclaw:/openclaw-config`) +- `CONFIG_ROOT=/openclaw-config` +- `MAIN_WORKSPACE_DIR=workspace` +- A single read-write mount for OpenClaw root (for example `~/.openclaw:/openclaw-config`) -`openclaw.json` and `org-chart.json` are always resolved from `CONFIG_FS_ROOT`. All other paths are -resolved from `WORKSPACE_FS_ROOT`. +`openclaw.json`, `org-chart.json`, shared folders (`projects`, `skills`, `docs`), and sub-agent +workspaces (`workspace-`) are resolved from `CONFIG_ROOT`. Main workspace virtual path `/` +resolves to `CONFIG_ROOT/MAIN_WORKSPACE_DIR`. ## What the workspace service provides @@ -48,8 +48,8 @@ OpenClaw Workspace Service (port 8080) │ Filesystem access ▼ Workspace PVC / directories -(`WORKSPACE_FS_ROOT`: workspace-coo/, workspace-cto/, skills/, docs/, projects/, etc. - `CONFIG_FS_ROOT`: openclaw.json, org-chart.json) +(`CONFIG_ROOT`: openclaw.json, org-chart.json, projects/, skills/, docs/, workspace-/... + `CONFIG_ROOT/MAIN_WORKSPACE_DIR`: main workspace for virtual path `/`) ``` In Kubernetes, the workspace service runs as a sidecar container in the OpenClaw pod and shares the @@ -87,24 +87,25 @@ internet: ## Workspace directory structure -A typical OpenClaw split-root layout: +A typical OpenClaw layout: ```text -/workspace ← WORKSPACE_FS_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 "/") +│ ├── 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-config ← CONFIG_FS_ROOT -├── openclaw.json ← OpenClaw configuration -└── org-chart.json ← Org chart 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) @@ -115,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` | @@ -147,11 +148,11 @@ curl -H "Authorization: Bearer " \ `.env` matches the token configured in the workspace service. **Workspace loads but models/agents fail** -`CONFIG_FS_ROOT` is not mounted correctly. Verify `/files/content?path=/openclaw.json` succeeds on +`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_FS_ROOT` is mounted read-only or points to the wrong directory. +`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`). From 133e7990e8c8ff50e9fdfd388332a2d745f845e8 Mon Sep 17 00:00:00 2001 From: Holden Omans Date: Tue, 3 Mar 2026 18:39:20 -0500 Subject: [PATCH 6/6] Document /workspace as canonical main OpenClaw path - 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 --- docs/getting-started/configuration.md | 2 +- docs/openclaw/setup.md | 2 +- docs/openclaw/troubleshooting.md | 13 +++++++------ docs/openclaw/workspace-service.md | 8 ++++---- 4 files changed, 13 insertions(+), 12 deletions(-) diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index 35244b4..4a4f2b5 100644 --- a/docs/getting-started/configuration.md +++ b/docs/getting-started/configuration.md @@ -78,7 +78,7 @@ variables, the workspace browser and skills features will be unavailable. Virtual path conventions: -- Main workspace: `/` +- Main workspace: `/workspace` - Sub-agent workspaces: `/workspace-` - Shared directories: `/projects`, `/skills`, `/docs` diff --git a/docs/openclaw/setup.md b/docs/openclaw/setup.md index af6245e..1de7041 100644 --- a/docs/openclaw/setup.md +++ b/docs/openclaw/setup.md @@ -61,7 +61,7 @@ services: - `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 `/` (no `/workspace` alias). +- Main workspace virtual path is `/workspace`. - Sub-agent workspaces resolve from `/workspace-` to `~/.openclaw/workspace-`. - 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). diff --git a/docs/openclaw/troubleshooting.md b/docs/openclaw/troubleshooting.md index 995d2d5..e0dddc5 100644 --- a/docs/openclaw/troubleshooting.md +++ b/docs/openclaw/troubleshooting.md @@ -158,15 +158,16 @@ OpenClaw agent config. --- -### `PATH_NOT_ALLOWED` when using `/workspace/...` +### `PATH_NOT_ALLOWED` for main workspace files -**Cause**: `/workspace` is no longer a valid virtual path alias for main workspace. +**Cause**: Main workspace paths must use the canonical `/workspace` namespace. **Fix**: -1. Use `/` for main workspace root -2. Use `/workspace-` for sub-agent workspaces -3. Use `/projects`, `/skills`, `/docs` for shared directories +1. Use `/workspace` for main workspace root +2. Use `/workspace/` for files under main workspace (not `/`) +3. Use `/workspace-` for sub-agent workspaces +4. Use `/projects`, `/skills`, `/docs` for shared directories --- @@ -234,7 +235,7 @@ curl -H "Authorization: Bearer " \ # List workspace files curl -H "Authorization: Bearer " \ - "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 " \ diff --git a/docs/openclaw/workspace-service.md b/docs/openclaw/workspace-service.md index 8656db8..e003255 100644 --- a/docs/openclaw/workspace-service.md +++ b/docs/openclaw/workspace-service.md @@ -26,8 +26,8 @@ For full MosBot functionality (agent discovery + Projects/Skills/Docs file edits - 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-`) are resolved from `CONFIG_ROOT`. Main workspace virtual path `/` -resolves to `CONFIG_ROOT/MAIN_WORKSPACE_DIR`. +workspaces (`workspace-`) are resolved from `CONFIG_ROOT`. Main workspace virtual path +`/workspace` resolves to `CONFIG_ROOT/MAIN_WORKSPACE_DIR`. ## What the workspace service provides @@ -49,7 +49,7 @@ OpenClaw Workspace Service (port 8080) ▼ Workspace PVC / directories (`CONFIG_ROOT`: openclaw.json, org-chart.json, projects/, skills/, docs/, workspace-/... - `CONFIG_ROOT/MAIN_WORKSPACE_DIR`: main workspace for virtual path `/`) + `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 @@ -93,7 +93,7 @@ A typical OpenClaw layout: /openclaw-config ← CONFIG_ROOT ├── openclaw.json ← OpenClaw configuration ├── org-chart.json ← Org chart configuration -├── workspace ← main workspace (MAIN_WORKSPACE_DIR, virtual path "/") +├── workspace ← main workspace (MAIN_WORKSPACE_DIR, virtual path "/workspace") │ ├── memory/ │ └── HEARTBEAT.md ├── workspace-coo/ ← sub-agent workspace (virtual path "/workspace-coo")