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.
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.pdfCopiedIt 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:
- the agent’s own workspace,
~/.openclaw/workspaceunless you moved it (a profile makes it~/.openclaw-<profile>/workspace, per the workspace docs); mediainside OpenClaw’s state folder,~/.openclaw/mediaby default;- OpenClaw’s own temporary folder, its canvas folder and the queue that holds undelivered attachments. Not
/tmpitself.
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.pdfCopiedFor 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
- The read tool is denied for this sender. Outbound media is checked against the same tool policy as the turn, including
tools.toolsBySenderand group policies, and whenreadis denied even the workspace is dropped from the list. Denyinggroup:fsdeniesreadwith it. A report on 2026.11.4 found a"*"entry that deniedreadblocking the owner’s own WebChat attachments, a bug still open in November 2026. Remote URLs still attached. - A sandboxed agent named a path inside its container. A path like
/workspace/exports/photo.jpgexists in the container, not on the host, and normal replies translate it. One open report (2026.10.7) finds replies sent after a background command finishes skip that step and the whole reply is dropped; the reporter’s way round was a workspace-relative path such as./exports/photo.jpg. How sandboxes map folders is in the sandbox guide. - The path does not exist. A typo or a folder never created can show up as this message rather than “not found” when OpenClaw’s folders are reached through a symlink, as in a Docker report. The fix was merged on November 8, 2026; its tests are not in 2026.11.6’s source, so it appears not to have reached that release. Check with
ls -lon the exact path. - A Windows path outside the workspace with the fence off. A report on 2026.10.9 (Windows 11, an agent on the Claude CLI runtime, Telegram) sees
C:\Data\Reports\file.pdfrefused withtools.fs.workspaceOnlyunset, against the documented default. It was open as of November 2026; copying the file under~/.openclaw/medialet the send through.
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.