OpenClaw的檔案治理

[boreal moon]

I'd like to ask: as time passes, the files in the system become increasingly cluttered because agents constantly generate new documents or scripts while executing tasks, and those files can be placed anywhere in the system. I feel this will become a ticking time bomb in the future. Is there a built-in mechanism or skill that can effectively manage this?

OpenClaw already has default paths to manage some files, but these are not enough. I hope to have something similar to "Add/Remove Programs," where I can track which features I've had the agent create. This way, when they are no longer needed, I can cleanly remove the features and properly handle associated settings without triggering errors.

[compact thistle]

Short version: partially, yes, but not as a full “Add/Remove Programs” system yet.

What OpenClaw has today:

• Per-agent workspace for normal file work: agents.defaults.workspace
  https://docs.openclaw.ai/concepts/agent-workspace
• Filesystem guardrail: tools.fs.workspaceOnly: true restricts file tools to the workspace
• Sandboxing: agents.defaults.sandbox can keep tool execution in ~/.openclaw/sandboxes instead of the host
  https://docs.openclaw.ai/gateway/sandboxing
• Session artifact cleanup: session.maintenance + openclaw sessions cleanup
  This only cleans session/transcript artifacts, not arbitrary files/scripts.
  https://docs.openclaw.ai/cli/sessions
• Plugin lifecycle management: plugins are the closest thing to install/uninstall tracking
  openclaw plugins list/install/uninstall ...
  https://docs.openclaw.ai/cli/plugins

What OpenClaw does not currently have:

• a general registry like “this feature created these files, changed these settings, and can now be fully uninstalled safely”

So your concern is valid. I think the safest current pattern is:

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      sandbox: {
        mode: "all",
        scope: "agent",
        workspaceAccess: "none",
      },
    },
  },

  tools: {
    fs: { workspaceOnly: true },
  },
}

My recommendation:

1. Keep agents confined to a workspace
2. Turn on tools.fs.workspaceOnly
3. Use sandboxing for anything exploratory
4. Put each workspace in private git
5. For durable capabilities, prefer plugins over ad hoc generated scripts

So, built-in cleanup exists for sessions and managed plugins, but not yet for arbitrary agent-created features/files across the system.

If you want, I can help sketch a “file governance” setup for OpenClaw that gets pretty close to what you want.

[boreal moon]

However, the main agent will need to call multiple sub-agents to execute a single task objective; if the sub-agents being called originate from different agents, it will affect the collaboration process.

[compact thistle]

Yep, that’s the core tradeoff.

In OpenClaw, a different agent is not just another worker. It has its own:

• workspace
• auth/profile state
• session store
• persona/instructions

So if the main agent spawns workers from other agents, you gain isolation, but you lose some natural shared context/file-state collaboration. That part is by design.
Docs: https://docs.openclaw.ai/concepts/multi-agent
Subagents: https://docs.openclaw.ai/tools/subagents

A good rule of thumb:

• Same task, shared files, shared repo → use same-agent subagents
• Different trust boundary / persona / credentials → use different agents

If you want multiple external coding harnesses to collaborate on the same project, ACP is the better fit. With ACP sessions, if you spawn across agents without cwd, it defaults to the target agent’s workspace, but you can force collaboration by giving them the same cwd.
Docs: https://docs.openclaw.ai/tools/acp-agents

So my recommendation is:

1. Create one “owner” agent per project/workspace
2. Let that agent spawn most workers under the same agent
3. Only use cross-agent workers when you explicitly want isolation
4. For Codex/Claude Code/Gemini style collaboration, use ACP and pin them to the same cwd

So, multi-agent is good for governance/isolation, but it should not be your main mechanism for intra-task collaboration. For that, same-agent subagents or same-cwd ACP sessions work better.

If you want, I can sketch a concrete architecture for:

• clean file governance
• multi-worker collaboration
• safe uninstall/cleanup paths

[boreal moon]

Suppose I have a main agent equipped with code, doc, test, and audit skills. These skills are handed over to sub-agents when the main agent delegates tasks. However, I also have a codex agent that performs better in coding and auditing. Therefore, for tasks involving code and auditing, the sub-agents of the codex agent will be selected instead.

[compact thistle]

Yes, that can work, but there’s one important mental-model tweak:

If the main agent delegates to a different agent like codex, that child is no longer just “main + a stronger coding brain”. It is operating as codex, with codex’s own:

• workspace
• auth/state
• skill visibility
• persona/instructions

So for your setup, I’d recommend this pattern:

Best pattern

• main = orchestrator / planner / final integrator
• codex = specialist executor for code + audit
• one canonical project root for the actual feature files

Then:

• docs/test tasks can stay with main or same-agent workers
• code/audit tasks can go to codex
• but both should work against the same project path, not separate long-lived copies

Practical rule

For one feature/repo, try to keep a single owner workspace.

Good:

• main decides
• codex edits/audits in the same repo/project path
• final state lands in one place

Risky:

• main writes feature files in workspace A
• codex writes related files in workspace B
• now cleanup/removal becomes messy fast

So the cleaner architecture is

1. Main agent = router
2. Codex agent = code/audit specialist
3. One project directory = source of truth
4. Explicit delegation rules so code/audit always go to codex

Also, if you go cross-agent a lot, I’d strongly suggest:

• explicit subagents.allowAgents
• requireAgentId: true
• tools.fs.workspaceOnly: true

That way the main agent doesn’t accidentally spray work into the wrong place.

Docs:

• Multi-agent: https://docs.openclaw.ai/concepts/multi-agent
• Subagents: https://docs.openclaw.ai/tools/subagents
• ACP agents: https://docs.openclaw.ai/tools/acp-agents

Honestly, if codex is always better at code/audit, I’d keep main thinner and let it specialize less. That usually makes governance cleaner too.

If you want, I can sketch a recommended topology for this exact main + codex + docs/test setup.

對，你抓到重點了。

只開 tools.fs.workspaceOnly，還不等於「子代理不能碰 workspace 外面」。

它限制的是 file tools，也就是這類路徑：

• read
• write
• edit
• apply_patch

但它不是完整 sandbox。
官方文件也有特別寫，workspace 是 default cwd，不是 hard sandbox。
https://docs.openclaw.ai/concepts/agent-workspace

所以如果子代理還有這些能力，就還是可能繞到 workspace 外：

• exec
• process
• 某些外部 runtime / ACP harness

簡單講

• tools.fs.workspaceOnly = true
  = 檔案工具盡量關在 workspace 內
• agents.defaults.sandbox ...
  = 執行環境真的隔離起來

如果你要比較硬的限制，建議要一起配

{
  tools: {
    fs: { workspaceOnly: true },
  },

  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        scope: "agent",
        workspaceAccess: "none", // 或 "ro"
      },
    },
  },
}

workspaceAccess 的差別：

• "none": 子代理只看到 sandbox workspace，主 workspace 不直接暴露
• "ro": 可以讀主 workspace，但不能寫

• "rw": 可以讀寫主 workspace

Docs: https://docs.openclaw.ai/gateway/sandboxing

另外一個很重要的點

如果你是 跨 agent 派工，限制會看 目標 agent 的有效設定。
也就是說，main 很嚴格，不代表 codex 也一樣嚴格。

所以真正安全的做法通常是：

1. tools.fs.workspaceOnly: true
2. 開 sandbox
3. 不需要就不要給 exec
4. 跨 agent 時，確保每個 target agent 也有同樣限制

如果你願意，我下一則可以直接幫你畫一個：

• main + codex
• 可協作
• 又不會把檔案灑得到處都是

的最小安全拓樸。

[boreal moon]

But if it's as you said, once tools.fs.workspaceOnly is enabled, sub-agents will only be able to write files within the workspace. In that case, how can they perform editing or auditing within the same project path?

[compact thistle]

Right, and the trick is:

tools.fs.workspaceOnly means “only inside the configured workspace”, not “only inside ~/.openclaw/workspace forever.”

So if you want sub-agents to edit/audit the same project, you usually do one of these:

Recommended

Set the project path itself as that agent’s workspace.

{
  agents: {
    defaults: {
      workspace: "~/Projects/my-repo",
    },
  },

  tools: {
    fs: { workspaceOnly: true },
  },
}

Then sub-agents can still edit and audit that repo, because for them, that repo is the workspace.

In other words

• workspaceOnly = true
• workspace = ~/Projects/my-repo

= they can work inside ~/Projects/my-repo, but not wander elsewhere with file tools.

---

Good patterns

Pattern A, one repo = one agent

Best governance, simplest mental model.

• main-project-a → workspace = ~/Projects/project-a
• main-project-b → workspace = ~/Projects/project-b

Pattern B, project is a subfolder of workspace

Also works, but broader blast radius.

• workspace = ~/Projects
• repo = ~/Projects/project-a

This allows access to all repos under ~/Projects, so I’d usually avoid it unless that’s intentional.

---

If sandboxing is also enabled

Then workspaceAccess matters:

• "ro": can audit/read the project, not write
• "rw": can edit the real project workspace
• "none": works in sandbox copy only, not the host project directly

Docs: https://docs.openclaw.ai/gateway/sandboxing

So the matrix is basically:

• real edits in same repo → workspace = repo root, workspaceOnly: true, sandbox rw or no sandbox
• audit only → workspace = repo root, sandbox ro
• safe isolated trial run → sandbox none, then apply patch later

---