openclaw - 💡(How to fix) Fix Bug: message tool filePath fails with LocalMediaAccessError in retry flows when agentId is not propagated

Bug: message tool filePath fails with LocalMediaAccessError when agent retries after a Telegram API error

Version: 2026.5.4

Summary: When an agent attempts to send a file via the message tool with filePath, and that send fails at the Telegram API level (e.g. "caption too long"), the bot's retry call hits a LocalMediaAccessError: Local media path is not under an allowed directory — even though agents.defaults.workspace is correctly configured and tools.fs.workspaceOnly: false is set.

Setup:

• Agent home: ~/.openclaw-agastya-keshav/ (HOME is overridden to this path in the service env)
• State dir resolves to: ~/.openclaw-agastya-keshav/.openclaw/
• Configured workspace: ~/.openclaw-agastya-keshav/workspace/ (set in agents.defaults.workspace)
• tools.fs.workspaceOnly: false

What happens:

1. First send attempt (via agent reply / MEDIA: attachment) succeeds — file is read and uploaded to Telegram. Telegram returns 400 "caption too long".
2. Bot retries using an explicit message(action=send, filePath="/path/to/file.xlsx") tool call.
3. Second attempt fails with LocalMediaAccessError: Local media path is not under an allowed directory: /Users/ram_macmini/.openclaw-agastya-keshav/workspace/file.xlsx

Root cause: In the retry code path, agentId is not propagated into the media access resolver (resolveAgentScopedOutboundMediaAccess). Without agentId, it falls back to getDefaultLocalRoots() which builds allowed roots from resolveStateDir():

{stateDir}/workspace = ~/.openclaw-agastya-keshav/.openclaw/workspace

This path differs from the configured workspace (~/.openclaw-agastya-keshav/workspace), so assertLocalMediaAllowed throws.

When agentId IS propagated (normal turn flow), getAgentScopedMediaLocalRoots(cfg, agentId) correctly reads agents.defaults.workspace from config and includes the actual workspace path. The bug is the inconsistency between these two code paths.

Workaround applied: Created a symlink at the state dir workspace path pointing to the real workspace:

ln -s ~/.openclaw-agastya-keshav/workspace ~/.openclaw-agastya-keshav/.openclaw/workspace

This ensures assertLocalMediaAllowed passes regardless of which code path is used.

Expected behaviour: agentId should always be propagated through retry/recovery flows when the message tool is invoked from an agent turn, so the agent-scoped workspace is consistently used.

Affected agents: Any agent whose HOME (and therefore state dir) is overridden in the service env to a non-standard location, and whose agents.defaults.workspace is set to a path outside {stateDir}/workspace.