linou518

Posted on Mar 16

OpenClaw macOS Workspace Config Ignored — Bug Report and Workaround

#openclaw #macos #multiagent #devops

When adding a Mac Mini M1 as a new node in OpenClaw, the agents.list[].workspace config was completely ignored. Here's the investigation and a working workaround.

Symptoms

After installing OpenClaw 2026.3.13 on macOS Ventura (Mac Mini M1) and adding an agent with an explicit workspace path:

agents:
  list:
    - id: my-agent
      workspace: /Users/openclaw/.openclaw/agents/my-agent/workspace

Every gateway restart ignores the setting and auto-generates ~/.openclaw/workspace/, pointing the session's cwd there. Default scaffold files (AGENTS.md, SOUL.md, TOOLS.md, etc.) get unpacked every time.

The custom agent workspace is never used.

Linux Works Fine

The same version 2026.3.13 on Linux (Ubuntu 24.04) respects agents.list[].workspace with absolute paths — no issues. The default ~/.openclaw/workspace/ isn't even created.

This is a macOS-specific bug.

What I Tried (All Failed)

Absolute path in agents.list[].workspace → ❌
agents.defaults.workspace fallback → ❌
Adding agentDir field → ❌ (doesn't exist)
openclaw agents add my-agent --workspace /path via CLI → ❌
Deleting ~/.openclaw/workspace/ before restart → ❌ (recreated every time)

Reading the source code, resolveAgentWorkspaceDir() correctly references the workspace config. But somewhere in the macOS code path, the result gets overwritten.

Workaround: symlink + chflags

A brute-force approach — redirect the default path to the correct location:

# Remove default workspace
rm -rf ~/.openclaw/workspace

# Symlink to the actual workspace
ln -s /Users/openclaw/.openclaw/agents/my-agent/workspace ~/.openclaw/workspace

# Protect the symlink with macOS immutable flag
sudo chflags -h uchg ~/.openclaw/workspace

chflags -h uchg is macOS-specific — it sets an immutable flag on the symlink itself, preventing the gateway from deleting or overwriting it on restart.

Result

After gateway restart, the session cwd correctly points to the custom workspace. Custom SOUL.md and TOOLS.md are loaded as expected. ✅

Limitations

This workaround is single-agent only. Since it redirects one path to one workspace, it doesn't work for multiple agents on macOS.

A proper fix needs to come from OpenClaw upstream. A GitHub Issue has been filed.

Takeaways

Always use absolute paths for workspace config. ~ is not expanded (by design).
macOS and Linux can behave differently even on the same version. Platform-specific bugs exist.
Always verify the session JSONL cwd after adding a new node. Config being correct doesn't guarantee correct behavior.
chflags is a powerful macOS tool for preventing daemon/package-manager file overwrites.

Environment

OpenClaw: 2026.3.13
macOS: Ventura (Mac Mini M1)
Verified working: Ubuntu 24.04

DEV Community