openclaw - 💡(How to fix) Fix Feature: Configurable `tools.mediaLocalRoots` for built-in media tools (pdf, image) [1 comments, 2 participants]

Problem

The built-in pdf and image tools have a hardcoded set of allowed local directories for file access. The allowed roots are:

• $STATE_DIR/media
• $STATE_DIR/agents
• $STATE_DIR/workspace
• $STATE_DIR/sandboxes
• The agent's own workspace directory (e.g., workspace-<agentId>)

When an agent tries to read a PDF from an arbitrary local path (e.g., /Users/jieli/Documents/悟昕/report.pdf), the tool rejects it with:

"error": "Local media path is not under an allowed directory: /Users/jieli/Documents/悟昕/report.pdf"

Current Workaround

Copy the file to the agent's workspace directory first via bash, then reference the workspace-local path. This works but is clunky for agents that routinely process files from user directories like ~/Documents, ~/Downloads, or project-specific paths.

Proposed Solution

Add a tools.mediaLocalRoots (or tools.fs.localRoots) config option to openclaw.json that accepts an array of additional directory paths:

{
  "tools": {
    "mediaLocalRoots": [
      "/Users/jieli/Documents",
      "/Users/jieli/Downloads"
    ]
  }
}

These paths would be merged into the roots returned by resolveMediaToolLocalRoots(), alongside the existing defaults. The path validation logic (realpath + prefix check) in assertLocalMediaAllowed() would remain unchanged — only the root list would grow.

Agent-level override (optional but nice)

Support per-agent overrides so agents with different trust levels can have different file access scopes:

{
  "agents": {
    "list": [
      {
        "id": "jmatrix",
        "tools": {
          "fs": {
            "localRoots": ["/Users/jieli/Documents", "/Users/jieli/Downloads"]
          }
        }
      }
    ]
  }
}

Security Considerations

• Keep the existing refusal of filesystem root (/) as a valid root entry (already enforced at line ~46192).
• The new roots are opt-in — default behavior doesn't change.
• Admin consciously broadens the sandbox per the paths they configure.

Environment

• OpenClaw version: 2026.3.13
• OS: macOS Darwin 25.3.0