Fix LocalMediaAccessError: path-not-allowed

If you see an error like:

• LocalMediaAccessError: path-not-allowed

…it means OpenClaw is blocking a local file path before it uploads/sends it.

This is good by default (it prevents accidental exfiltration of sensitive files), but it can be frustrating when you actually want to send screenshots.

When it happens

Typical triggers:

• openclaw message send --media ~/xxx.png
• a skill/tool produces a local file and then tries to attach it
• you are sending through a channel that enforces a local path allowlist

Quick diagnosis (2 minutes)

1. Confirm the actual path you’re trying to send.

   • Expand ~ yourself and check the full absolute path.

2. Check whether the channel supports local media sending the way you expect.

   • Some channels require an upload step, and the gateway will enforce stricter path policies.

3. Run with a “known safe” file

   • Put a test image into a dedicated folder like ~/openclaw-media/ and retry.

Fix checklist

1) Create a dedicated media folder

Pick a folder whose only purpose is “files that are allowed to be sent out”:

mkdir -p ~/openclaw-media

Move/copy your test image into it:

cp ~/Downloads/test.png ~/openclaw-media/test.png

2) Allowlist that folder (recommended)

Instead of allowing “any path”, allowlist only a controlled directory.

In your OpenClaw config, set the channel local roots to include the folder you just created.

Example concept (field names may differ per channel integration):

• allow: ~/openclaw-media (and optionally a workspace output dir)
• deny: everything else

3) Re-run the send

openclaw message send --media ~/openclaw-media/test.png

If it works, your config + path policy are fine.

4) If it still fails: common root causes

• Config path is wrong (you set ~ but the runtime doesn’t expand it)

  • fix: use absolute path like /home/<user>/openclaw-media

• You changed config but didn’t restart

  • fix: restart the gateway/service after config changes

• You’re editing a different environment config

  • fix: confirm which openclaw.json is active

• The channel implementation enforces stricter checks

  • fix: look for a dedicated localRoots/mediaRoots setting specific to the channel

Why we recommend “folder allowlist” (not any)

Allowing any local path is convenient but risky:

• accidental leakage of private keys or tokens
• sending files outside your intended project
• ambiguous provenance of files produced by tools

A dedicated allowlisted folder keeps the UX good and the risk low.

Related

• Source issue: https://github.com/openclaw/openclaw/issues/39506