Summary

• Problem: Explore per-agent worker isolation, VFS scratch storage, and host filesystem capabilities #78096 tracks a long-term architecture question across per-agent runtime isolation, scratch storage, and safe real-host filesystem mutation.
• Why it matters: those layers solve different security and product problems, and blending them risks treating Node permissions or VFS scratch storage as replacements for fs-safe host mutation.
• What changed: added a dedicated filesystem capability model doc, linked it from secure file operations, sandboxing, and security docs, and added it to Mintlify navigation.
• What did NOT change (scope boundary): no runtime behavior, dependency, sandbox backend, or plugin API changes.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes Explore per-agent worker isolation, VFS scratch storage, and host filesystem capabilities #78096
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: converts the architecture tracking note into durable docs and navigation.
• Real environment tested: local docs checkout on Linux with Node 24.15.0 and pnpm 10.33.2.
• Exact steps or command run after this patch: pnpm exec oxfmt --check --threads=1 docs/gateway/security/filesystem-capability-model.md docs/gateway/security/secure-file-operations.md docs/gateway/sandboxing.md docs/gateway/security/index.md CHANGELOG.md docs/docs.json; node scripts/check-docs-mdx.mjs docs.
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): copied terminal output: Docs MDX check passed (620 files, 13827ms). All matched files use the correct format. Finished in 11760ms on 5 files using 1 threads.
• Observed result after fix: the new page passes docs validation and is present in docs/docs.json navigation under Security and sandboxing.
• What was not tested: live Mintlify deployment.
• Before evidence (optional but encouraged): Explore per-agent worker isolation, VFS scratch storage, and host filesystem capabilities #78096 existed only as an issue note with no docs page.

Root Cause (if applicable)

For bug fixes or regressions, explain why this happened, not just what changed. Otherwise write N/A. If the cause is unclear, write Unknown.

• Root cause: N/A.
• Missing detection / guardrail: N/A.
• Contributing context (if known): N/A.

Regression Test Plan (if applicable)

For bug fixes or regressions, name the smallest reliable test coverage that should catch this. Otherwise write N/A.

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: scripts/check-docs-mdx.mjs, oxfmt.
• Scenario the test should lock in: docs front matter, links, MDX syntax, docs navigation JSON, and formatting stay valid.
• Why this is the smallest reliable guardrail: this is docs-only with no runtime behavior.
• Existing test that already covers this (if any): docs MDX check and formatter.
• If no new test is added, why not: docs-only architecture guidance does not need runtime test coverage.

User-visible / Behavior Changes

Adds a new docs page: https://docs.openclaw.ai/gateway/security/filesystem-capability-model.

Diagram (if applicable)

Before:
[issue note] -> [no durable docs page]

After:
[issue note] -> [filesystem capability model docs] -> [linked from security/sandboxing navigation]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: Linux
• Runtime/container: Node 24.15.0, pnpm 10.33.2
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): N/A

Steps

1. Open docs/gateway/security/filesystem-capability-model.md.
2. Confirm docs/docs.json includes gateway/security/filesystem-capability-model under Security and sandboxing.
3. Run the docs formatter and MDX checks.

Expected

• Docs page exists, links resolve, navigation includes the page, and checks pass.

Actual

• Formatter passed and docs MDX check passed for 620 files.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: docs page content, security/sandboxing links, docs navigation entry, changelog entry, formatter, MDX docs check.
• Edge cases checked: Node permission wording checked against official Node permissions docs; scope states this is not a runtime implementation.
• What you did not verify: live docs deployment.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: readers mistake the model page for implemented VFS or worker isolation.
  • Mitigation: the page explicitly labels those as future experiments and says no runtime behavior changed.