OpenClaw’s Remote iMessage Image Bug Is What Happens When Media Pipelines Cross Machines

OpenClaw’s remote iMessage media bug is narrow enough that most users will never hit it. That is exactly why it is worth covering. The interesting failures in agent platforms are often not the universal ones. They live at the handoff points: one machine sees a file, another machine owns the runtime, a sandbox policy is technically correct, and the user gets no useful result.

Issue #87089 describes that handoff failure cleanly. The setup is a Linux OpenClaw gateway bridging iMessage through a remote Mac over SSH/SCP using the native imsg bridge. Attachments are enabled, the config includes remote roots such as /Users/*/Library/Messages/Attachments, and inbound photos should be fetched from the Mac, staged locally, and then passed to media understanding. Instead, the image-analysis path receives the raw Mac path first and rejects it: Local media path is not under an allowed directory: /Users/kaien/Library/Messages/Attachments/.../IMG_0351.jpeg.

The bug is not that the sandbox rejected the path. The sandbox was right. The bug is that the runtime asked the sandbox the wrong question too early.

Remote media is a staged capability, not just a pathname

On a Mac-native OpenClaw install, an iMessage attachment path under ~/Library/Messages/Attachments is a local file path. The runtime can validate it against attachment-root policy and pass it to the image tool. On a Linux gateway, that same string is not a file the gateway can read. It is a promise: there is media on another machine, under a permitted remote root, and the system must use the remote-host staging pipeline to fetch and rewrite it into a local sandbox cache before analysis.

According to the issue, the iMessage monitor does the expected remote-host setup. When channels.imessage.remoteHost is configured, it skips local staging, passes raw media attachment references, and sets MediaRemoteHost, expecting stageSandboxMedia to SCP-fetch and rewrite the path. The ordering problem comes later: get-reply runs applyMediaUnderstandingIfNeeded(...) before stageSandboxMedia(...). The image tool sees the remote Mac path before it has been transformed into a local staged artifact.

The reporter patched the built JavaScript locally to stage sandbox media first when MediaRemoteHost is set and inbound media has not yet been staged. After restart, iMessage photos were SCP-fetched and analyzed correctly. ClawSweeper confirmed current main and v2026.5.22 still run media understanding before sandbox media staging for this path, labeling it a valid, narrow ordering bug with source reproduction, P1, impact:message-loss, and the repo’s “diamond lobster” issue rating.

The security boundary and the feature want the same fix

The wrong response would be to broaden allowed local roots on the Linux gateway until the error disappears. That treats a pipeline-ordering bug as a permissions bug. Worse, it weakens the boundary while still not making the remote file local. A Linux process cannot safely analyze a Mac path by being told to trust it harder.

The correct fix is preserving the invariant: remote media must become local, staged, policy-checked media before any understanding tool sees it. That keeps the security model intact while restoring the feature. The staged artifact should carry provenance — original channel, account, remote host, remote path, local cache path, and expiry — so later tools know they are handling a capability granted by the inbound message context, not a random filesystem request.

This distinction matters beyond iMessage. Agent platforms increasingly span phones, desktops, browsers, containers, cloud workers, local files, and remote shells. A “file” may be a real local path, a staged upload, a browser download, a mobile attachment, a remote-host reference, or a tool-produced artifact. Those are different capabilities. Flattening them all into strings is how systems drift into either false denials or unsafe allowances.

For operators, the affected slice is specific: Linux gateway, remote Mac iMessage bridge, includeAttachments: true, media understanding enabled, and image attachments arriving over iMessage. If that is your setup, watch logs for raw /Users/.../Library/Messages/Attachments paths in image-tool failures. Do not fix it by expanding local roots on the Linux host. Upgrade when a release fix lands or apply a focused staging-order patch if you are comfortable carrying local changes.

For maintainers, this deserves a regression test that models the remote-host path explicitly: inbound media starts as a Mac attachment path with MediaRemoteHost, staging rewrites it to a local sandbox path, media understanding receives only the local staged artifact, and path policy rejects any attempt to bypass that rewrite. The test should fail if image understanding ever sees the raw remote path first.

The broader lesson is that multi-machine media pipelines need typed handoffs. “Here is a path” is not enough. The runtime needs to know whether the path is local, remote, staged, expired, user-supplied, tool-produced, or channel-authorized. Those distinctions are where both reliability and security live.

OpenClaw’s iMessage issue is not a sign the sandbox is too strict. It is a sign the runtime used a capability before it existed. Remote media is not “just a file”; it is a staged capability. Use it before staging and you get exactly the kind of failure a sandbox is supposed to produce.

Sources: GitHub issue #87089, PR #86569, PR #86705, issue #30170