OpenClaw pathing/mount mismatches across workspace service, API, and docs (tracking)

[kalinon]

Summary

OpenClaw integration currently has compounded pathing and mount assumptions across workspace-service, API, and docs that break fresh MacBook/local installs where config and workspace roots are independent.

This tracking issue captures the concrete failures and coordinates fixes across:

• workspace service routing/env contract
• API path normalization/agent workspace mapping
• documentation and deployment examples

Environment

• Host: macOS (MacBook)
• OpenClaw config path: ~/.openclaw
• OpenClaw workspace path: ~/.openclaw/workspace

Current documented setup (problematic)

services:
  mosbot-workspace:
    image: ghcr.io/bymosbot/mosbot-workspace-service:latest
    environment:
      WORKSPACE_SERVICE_TOKEN: your-secure-token # required
      WORKSPACE_ROOT: /workspace
    volumes:
      - ~/.openclaw/workspace:/workspace:ro
    ports:
      - "8080:8080"

Issues encountered

1) Workspace status returns 500 on fresh install

/api/v1/openclaw/workspace/status returns 500 with ENOENT for /workspace/workspace.

Observed error:

{"error":{"message":"OpenClaw workspace service error: 500 {\"workspace\":\"/workspace\",\"exposedRoot\":\"/workspace/workspace\",\"workspaceSubdir\":\"workspace\",\"exists\":false,\"accessible\":false,\"error\":\"ENOENT: no such file or directory, stat '/workspace/workspace'\"}","status":500}}

This implies accidental nested expectation:

/workspace
  /workspace

2) Projects/Skills/Docs fail under read-only mount

With :ro mount, UI operations that create dirs/files fail (mkdir '/workspace/workspace/projects').

Observed error:

{"error":{"message":"OpenClaw workspace service error: 500 {\"error\":\"ENOENT: no such file or directory, mkdir '/workspace/workspace/projects'\",\"path\":\"/files\"}","status":500}}

Removing :ro fixes write behavior, indicating docs/examples were incorrect for normal UI usage.

3) Workspaces page path mismatch and allowlist failures

Default agents from /api/v1/openclaw/agents returned host-absolute paths like:

• /home/node/.openclaw/workspace
• /home/node/.openclaw/_archived_workspace_main

These produced confusing nested lookups (e.g. /workspace/workspace/workspace) and allowlist/path-not-found failures in workspace file endpoints.

4) Model Fleet page 404 for /api/v1/models

GET /api/v1/models attempts GET /files/content?path=/openclaw.json, which failed when config root was not mounted/treated independently from workspace root.

Root causes

• Coupled root/subdir assumptions (WORKSPACE_ROOT + WORKSPACE_SUBDIR) in service behavior.
• Docs/examples implied read-only workspace mount despite required write operations.
• API accepted host-absolute workspace/config paths from agents but did not consistently remap/normalize all common prefixes (including ~/.openclaw).
• Missing explicit workspace handling for default/main agent when workspace is omitted.

Expected behavior

• Config and workspace roots are independent and explicitly configured.
• Workspace service routes config files (/openclaw.json, /org-chart.json) to config root and everything else to workspace root.
• API remaps known external path prefixes (/home/node/.openclaw, ~/.openclaw) into virtual paths before allowlist checks.
• Default/main agent resolves to workspace root when workspace is omitted.
• Docs reflect read-write mount requirement for regular dashboard file flows.

Tracking PRs

• Workspace service split-root refactor: refactor(openclaw): split workspace and config filesystem roots #2
• API remap + agent workspace normalization: feat(openclaw): normalize host paths for split-root workspace routing mosbot-api#7
• Documentation updates: docs(openclaw): document split roots and host-path remap defaults mosbot-docs#2

[kalinon]

Linked PRs for this tracking issue:

• Workspace service: refactor(openclaw): split workspace and config filesystem roots #2
• API: feat(openclaw): normalize host paths for split-root workspace routing mosbot-api#7
• Docs: docs(openclaw): document split roots and host-path remap defaults mosbot-docs#2

Each PR now includes an explicit reference to this issue.