Problem

The exec allowlist controls which binaries an agent can run but cannot restrict which paths those binaries touch. A permitted /bin/ls on ~/workspace is equally permitted on ~/.ssh. There is no mechanism to scope an agent's filesystem access to specific directory trees. Closes #39979.

Root Cause

No path-level enforcement exists at either the tool layer or the OS layer. All read/write/edit/exec tool calls succeed on any path the OS user can access.

Fix

Add an optional ~/.openclaw/access-policy.json sidecar that defines per-agent RWX rules enforced at two layers:

• Tool layer — read/write/edit/exec tools resolve symlinks (safeRealpath) then check the resolved path against the active policy before executing
• OS layer (macOS) — exec commands are wrapped with sandbox-exec using a generated Seatbelt (SBPL) profile; on Linux with bwrap installed, bubblewrap bind-mount sandboxing is used instead. On Linux without bwrap or on Windows, exec runs unconfined with a one-time warning.

Policy format:

{
  "version": 1,
  "agents": {
    "*": {
      "policy": {
        "/**":            "r--",
        "~/workspace/**": "rwx",
        "/tmp/**":        "rw-",
        "~/.ssh/**":      "---"
      },
      "scripts": {
        "policy": { "/tmp/**": "rw-" },
        "~/bin/deploy.sh": {
          "sha256": "abc123...",
          "policy": { "~/deploy/**": "rwx" }
        }
      }
    },
    "myagent": { "policy": { "~/workspace/**": "rwx" } }
  }
}

Policy semantics:

• policy — the path→perm rule map inside each agent block. Glob→perm; longest-match-wins using expanded pattern lengths. "---" means deny all. "/**": "r--" is a permissive catch-all. No rule match = implicit "---" (fail-closed).
• agents["*"] — base policy applied to every agent. Put org-wide rules here. Can include both policy (path rules) and scripts (per-script overrides).
• agents["myagent"] — per-agent overrides merged on top of agents["*"]. policy rules are shallow-merged (agent wins on collision). scripts entries are deep-merged: the base sha256 is always preserved and cannot be overridden by an agent block.
• scripts{} — per-argv[0] hash-verified policy overlay; fires only when the exec target matches a named script key. sha256 mismatch is a hard exec denial. Script override rules are emitted after base rules in the OS sandbox profile (last-match-wins) so they can reach inside broadly denied subtrees.
• scripts["policy"] — shared path rules merged as the base for every per-script entry in the same scripts block. Only takes effect when a script key matches — a scripts block with only scripts["policy"] and no named script keys has no effect.
• Per-script entries: policy block adds/narrows rules for that script; sha256 is optional integrity check.
• Permission strings: "rwx", "rw-", "r--", "-w-", "r-x", "--x", "---".

Design decision — no deny[], no default, no agents["policy"]:

• "---" rules and a "/**" catch-all are sufficient — no separate deny mechanism needed.
• default was dropped: it is syntactic sugar for "/**": "perm".
• agents["policy"] (a previous iteration's reserved base key) was removed in favour of agents["*"], which uses the natural wildcard semantics already established by exec allowlists. No new reserved keywords.

Security hardening included:

Testing

Unit tests across access-policy.test.ts, access-policy-file.test.ts, exec-sandbox-bwrap.test.ts, exec-sandbox-seatbelt.test.ts (bwrap/seatbelt tests skipped on non-Linux/non-macOS).

Covers: direct reads/writes, tilde expansion, path normalization, variable expansion, interpreter indirection, symlink attacks, SBPL deny ordering, bwrap mount ordering, "---" rule mount suppression, narrowing under permissive base, seatbelt permissive exec baseline, /tmp conditional baseline, pattern specificity, per-script hash verification, agent wildcard merge, bare-dir auto-expand (top-level + per-script), validation dedup, env-prefix argv0 resolution, env -S recursion all three forms, quoted env argv0 look-through, symlink script key matching, mtime cache, scripts["policy"] shared rules, scripts["policy"] reserved key skip.

Known limitations / follow-ups

• **/abc specificity — length-based longest-match uses raw pattern string length, not semantic depth. Avoid mid-path ** in rules; use explicit paths or suffix globs instead.
• Mid-path wildcards at OS layer — patterns like /home/*/secrets/** cannot be enforced precisely by bwrap/Seatbelt. Non-deny rules use the longest concrete prefix as an approximate OS target for r/w; exec is omitted from the approximation. Tool-layer enforcement is precise. Use trailing-** patterns for full OS enforcement.
• bash script.sh bypasses exec bit — readable scripts can be run via interpreter regardless of x bit. Use "---" to truly block execution.
• bwrap exec-bit not enforced at OS layer — r-- and r-x bind mounts are equivalent at the Linux mount level.
• "---" rule on a file path (bwrap) — --tmpfs only accepts directories; file-specific "---" rules are skipped at the OS layer with a one-time warning. Deny the parent directory instead for OS-level enforcement.
• scripts["policy"] requires a matching script entry — shared script rules only apply when an exec target matches a named key in scripts. A scripts block with only scripts["policy"] and no named entries has no effect.
• No approval/ask flow for policy misses — fail-closed; interactive on-miss mode is a future phase.
• Glob/find reveals filenames — directory listing syscalls are not blocked even when file content is denied.
• Windows and Linux-without-bwrap — exec runs unconfined (warned once per process).
• A2A/MCP cross-agent delegation — uses the calling agent's policy; no automatic narrowing.

AI-assisted (Claude) · Regression tests added · Fix reviewed and understood