#File system structure in openclaw

11 messages · Page 1 of 1 (latest)

civic jackal
#

Hey @wintry ferry I opened my .openclaw dir yesterday night and I got new dirs that act like agent workspaces inside my main agent for my other agents. Is it the new default architecture or is it my agent that drifted?

Now I have workspaces for each agent directly inside .openclaw dir and i got those new dirs in my main agent.

I'm not sure if I should migrate to agents workspaces inside main agent main workspace or I should enforce my original setup 🤔

undone berryBOT
#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

rough archBOT
wintry ferryBOT
#

Let me check the local docs/source so I don’t guess here.

#

Found the current docs, reading the agent workspace and multi-agent bits now.

#

What does openclaw --version show?

This looks like a real recent behavior change, not just agent drift.

I checked current docs/source, and there was a fix on Apr 2 (#59789) so non-default agents now inherit agents.defaults.workspace as a base when they do not have their own explicit workspace.

So if you have something like:

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [{ id: "main" }, { id: "work" }],
  },
}
#

then work can resolve to:

~/.openclaw/workspace/work

That is why it can suddenly look like you have agent workspaces inside the main workspace.

Separately, agent state is still expected under:

~/.openclaw/agents/<agentId>/

So, my recommendation:

  • If you want clean isolation and less confusion, set every agent's workspace explicitly, for example:
#
  • ~/.openclaw/workspace-main
    • ~/.openclaw/workspace-work
  • If you intentionally want one shared umbrella tree, the new behavior is fine.

I would not migrate everything into the main agent workspace unless that shared layout is actually what you want.

Docs:

If you paste your agents config block plus openclaw --version, I can tell you exactly whether your current layout is expected.

civic jackal
wintry ferryBOT
#

Biggest advantage, less config and fewer surprise fallbacks.

What changed is mostly a workspace resolution default, not a whole new architecture. The upside is:

  • One base path to manage. Set agents.defaults.workspace once, extra agents land under it.
  • Cleaner portability. If you move/backup that root, all agent workspaces move with it.
  • More predictable than old fallback behavior. Non-default agents no longer jump somewhere else just because they were missing an explicit workspace.
  • Nice for “workspace family” setups where you intentionally want one parent dir with multiple agent folders.

But there are tradeoffs:

  • Blurrier isolation. It feels like subfolders of the main brain, even if state/auth are still separate.
  • More clutter in the main workspace tree.
  • Easier to accidentally mix files if you think of the main workspace as a clean personal memory repo.
  • Git backups can get weird if your main workspace repo now contains child agent workspaces.

So I’d say: