GuidesRunning & maintaining

OpenClaw "Local media path is not under an allowed directory"

Why OpenClaw refuses to attach a local file to Telegram, WhatsApp, Discord or WebChat, which folders it allows, and how to send the file anyway.

November 19, 2026The Everpod team
The short answer

OpenClaw only attaches a file from your computer when it sits in a folder it allows, and this file did not. The folders always allowed are the agent’s workspace (~/.openclaw/workspace by default), the media folder in OpenClaw’s state folder (~/.openclaw/media) and a few of OpenClaw’s own. Anywhere else is allowed only while tools.fs.workspaceOnly is off and the agent is allowed its read tool. The quick fix: copy the file into the workspace and send that copy. If it already was in the workspace, check the path exists and, for a sandboxed agent, that it is not a path from inside the container.

What you see

The send fails and the log or the agent’s reply carries, with the file’s path at the end:

LocalMediaAccessError: Local media path is not under an allowed directory: /home/you/reports/q3.pdf
Copied

It comes from the check OpenClaw runs before reading a local file for any channel, so Telegram, WhatsApp, Discord, WebChat and openclaw message send --media all fail the same way. In the source as of OpenClaw 2026.11.6, the path is resolved through any symlinks and compared with a list of allowed folders; if none contains it, the send is refused. One user report of 2026.11.4 shows the line continuing “Use a file inside the agent workspace or another allowed media folder.” A different message, “Local media file not found”, means the folder was allowed and the file is missing.

Which folders are allowed

Per the list of media roots in 2026.11.6, every send may read from:

On top of those, OpenClaw adds the folder holding the file you are sending, which is what lets an agent attach any file it can read. That widening happens only when tools.fs.workspaceOnly is not set to true (an agent’s own setting wins over the global one) and the read tool is allowed for that agent. OpenClaw’s attachments FAQ states the same from the user’s side: off, the default, “lets structured local media sends use host-local files the agent can already read”; on, it “limits local-path sends to workspace, temp/media-store, and sandbox-validated files.”

Fix it by moving the file, not the fence

Put the file where every setting allows it and send it from there:

cp /home/you/reports/q3.pdf ~/.openclaw/workspace/
openclaw message send --target +15555550123 --message "Here you go" \
  --media ~/.openclaw/workspace/q3.pdf
Copied

For an agent, the same: ask it to copy the file into its workspace first and attach the copy. OpenClaw’s FAQ says outbound attachments “must use structured media fields such as media, mediaUrl, path, or filePath”; the file-sharing guide covers why a path mentioned in a reply is not a download.

To see whether the fence is on, run openclaw config get tools.fs.workspaceOnly. If it says true and you want agents to send any file they can read, openclaw config unset tools.fs.workspaceOnly returns it to the default. Weigh that first. OpenClaw’s FAQ is plain that the check “is not a secret scanner”: with the fence off, a config file the agent can read can be attached too, and it advises keeping secrets outside readable paths “or keep tools.fs.workspaceOnly=true for stricter local-path sends.” If someone else set it on a shared machine, it is theirs to change.

When the file was already in an allowed folder

One case is not a send at all. With the fence on, an agent could not open the images it had just generated, which OpenClaw saves under media/tool-image-generation in the state folder, though sending them to you still worked; that report (2026.11.2) was closed by a fix on November 14, 2026.

Older reports, from February 2026, of files in the workspace itself being refused were fixed in the releases after them. If you are on an early-2026 release and see that, update before anything else.

Give your AI agents a permanent cloud computer.

We set it up and secure it, so all you do is use them. Run Claude Code, Codex or any agent you use, more at once than your laptop can hold, and keep them working when it’s closed. Or have OpenClaw set up and run for you.

See the developer pod

From $24/mo · your own plan or API key

Get your OpenClaw agent

$29/mo, cancel anytime · model usage included