diff --git a/docs/getting-started/configuration.md b/docs/getting-started/configuration.md index bb4096d..4a4f2b5 100644 --- 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-` +- Shared directories: `/projects`, `/skills`, `/docs` ## OpenClaw Gateway diff --git a/docs/openclaw/setup.md b/docs/openclaw/setup.md index d0b3a6e..1de7041 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/node/.openclaw ports: - '18789:18789' @@ -48,16 +48,26 @@ services: 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-` 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). + +::: + 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 index 5c0b488..e0dddc5 100644 --- 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 " \ --- +### 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 " \ + "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/` for files under main workspace (not `/`) +3. Use `/workspace-` 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 " \ # 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 07bb2b3..e003255 100644 --- 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-`) 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-/... + `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 " \ **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`).