Why does `system.run` fail on macOS nodes?

The macOS OpenClaw node software (version 2026.3.0 or similar) is missing the `system.run.prepare` command. OpenClaw requires this preparatory command as part of a security handshake before executing `system.run`. Without it, the execution is blocked.

Can I just add `system.run.prepare` to `allowCommands`?

No, `allowCommands` in your gateway configuration only permits commands that the node *already* supports and advertises. You cannot use it to enable commands that are missing from the node's software itself.

Is there a fix for `system.run.prepare` on macOS?

As of the discussion on GitHub issue #37591, the fix requires an update to the macOS node software itself to include `system.run.prepare`. There is no workaround within the existing gateway configuration or node settings to enable it.

Fix: macOS Node Missing system.run.prepare Prevents system.run

TL;DR — Quick Fix

Your macOS OpenClaw node version doesn't support `system.run.prepare`, blocking `system.run`. The workaround is using alternative tools like ffmpeg for screenshots.

Run Diagnostics

Next Step

Fix now, then reduce repeat incidents

If this issue keeps coming back, validate your setup in Doctor first, then harden your config.

Open Doctor Harden Config

Error Signal

Error: node command not allowed: the node (platform: macOS 26.3.0) does not support "system.run.prepare"

What's Happening

You're seeing an error like Error: node command not allowed: the node (platform: macOS 26.3.0) does not support "system.run.prepare" when trying to run commands on your macOS OpenClaw node. This happens because the system.run command requires a handshake command, system.run.prepare, which your current macOS node software doesn't implement.

The Fix

Unfortunately, there's no direct fix for this on the macOS node itself within the current OpenClaw versions discussed.

The official GitHub issue (openclaw/openclaw#37591) indicates that the macOS node software needs to be updated to include the system.run.prepare command. Until that update is available and applied, you cannot use system.run on this node.

Workaround:

The user in the discussion found a workaround for taking screenshots by avoiding peekaboo and instead using ffmpeg for frame extraction:

ffmpeg -i screen_record.mp4 -vframes 1 screenshot.png

This bypasses the need for system.run entirely for this specific task. You'll need to adapt this approach for other tasks that relied on system.run.

Why This Occurs

OpenClaw's execution flow for commands like system.run requires a security handshake. The system.run.prepare command is part of this handshake, verifying the node's readiness and capabilities. If the node software (in this case, the macOS version) doesn't include or advertise system.run.prepare in its describe.commands list, OpenClaw's gateway prevents the system.run command from executing. This is a safety mechanism.

The nodes.allowCommands setting on the gateway only enables commands that the node already supports. It cannot add or enable commands that the node binary itself doesn't expose.

Run openclaw nodes describe <your-node-id> on your gateway to see exactly which commands your node reports it supports. You'll likely see system.run listed, but not system.run.prepare.

Prevention

Keep your OpenClaw node software updated. When a new version is released for macOS that includes system.run.prepare, update your node and re-pair it with the gateway. Monitor the relevant GitHub issues for progress on this feature.

For now, stick to commands explicitly listed in your node's describe.commands output or rely on the workaround provided for tasks like screenshots.

Last Updated: March 2026

Did this guide solve your problem?