Mac Node Bridge

Mac Node Bridge

Use this skill when your gateway runs on Linux but the real tool lives on a Mac node.

This skill does not patch bundled OpenClaw skills. It creates explicit SSH wrappers and verification steps so a Linux gateway can call macOS binaries on connected nodes in a way that is publishable, repeatable, and auditable.

Use This Skill For

• imsg, remindctl, memo, things, peekaboo, or other macOS-only CLIs
• Homebrew-installed business tools that only exist on a Mac node
• Linux gateway + one or more Mac nodes where you want a stable remote execution path
• ClawHub-ready skills that should target Macs cleanly instead of mutating bundled Linux assumptions

Do Not Use This Skill For

• Linux-native CLIs that should simply be installed on the gateway
• UI-only pairing problems
• Cases where you do not have passwordless SSH from the gateway to the Mac node
• Forcing bundled OpenClaw macOS skills to show green on Linux by patching core files

Requirements

• Linux gateway can SSH to the target Mac node without a password
• Remote binary exists on the Mac node and is executable
• The Mac node already has any required macOS privacy permissions granted
• You know which Mac should own the tool

Path Rules

Use dynamic paths by default.

• Wrapper install dir defaults to OPENCLAW_BIN_DIR, then XDG_DATA_HOME/openclaw/bin, then HOME/.openclaw/bin
• Preset installs resolve remote binaries dynamically with command -v, remote brew --prefix, and common Homebrew prefixes
• Use --target-dir or --remote-bin only when you intentionally need to override the defaults

Trust Model

This skill assumes:

• the Linux gateway is the orchestrator
• each Mac node is a separately trusted execution surface
• cross-host access must be narrow, explicit, and reversible

Plan around these rules:

• use strong, scoped credentials and per-node trust, not one broad shared secret
• require the Mac side to prove identity before the gateway accepts orchestration signals
• give each wrapper only the minimum action it needs
• log cross-host setup, verification, and deployment steps
• fail soft when a Mac is unavailable; do not crash the whole system

Read references/security-model.md before publishing or extending this skill.

Workflow

1. Pick The Owning Mac

Default pattern:

• M1: always-on services like imsg
• MacBook Pro: heavier interactive or business tooling

If you are unsure, verify first:

scripts/verify-node-tool.sh --host agent1@mac-mini.local --tool imsg
scripts/verify-node-tool.sh --host agent2@macbook-pro.local --tool remindctl

If the tool lives outside the normal shell path or Homebrew defaults, pass an explicit path:

scripts/verify-node-tool.sh --host agent2@macbook-pro.local --bin /custom/path/remindctl

2. Install A Wrapper On The Gateway

For a known tool preset:

scripts/install-preset.sh \
  --tool imsg \
  --host agent1@mac-mini.local

Or install a generic wrapper:

scripts/install-wrapper.sh \
  --name remindctl-mbp \
  --host agent2@macbook-pro.local \
  --remote-bin /opt/homebrew/bin/remindctl

Override the wrapper directory only when you need a non-default layout:

scripts/install-preset.sh \
  --tool memo \
  --host agent1@mac-mini.local \
  --target-dir "$HOME/.local/bin"

3. Verify The Wrapper

"${OPENCLAW_BIN_DIR:-${XDG_DATA_HOME:-$HOME/.openclaw}/openclaw/bin}"/imsg chats --limit 1
"${OPENCLAW_BIN_DIR:-${XDG_DATA_HOME:-$HOME/.openclaw}/openclaw/bin}"/remindctl-mbp lists

If the wrapper works but a bundled OpenClaw skill still shows gray, that is expected on a Linux gateway. Use the wrapper-backed workflow or publish a wrapper-aware skill instead of patching OpenClaw core.

4. Publish Wrapper-Aware Skills

When building a new ClawHub skill on top of this bridge:

• call the wrapper through a configurable path contract, not a user-specific absolute home path
• document which node owns the tool
• keep secrets and tokens on the node or gateway config, not in the skill folder
• treat the wrapper as the stable contract

Read references/publish-pattern.md before turning a one-off wrapper into a public skill.

Security Rules

• Use a dedicated SSH key for gateway-to-node wrappers whenever possible
• Use non-root accounts on the Mac nodes
• Prefer one wrapper per tool per node instead of a single unrestricted shell bridge
• Never store API tokens, app secrets, or OAuth cookies in the skill folder
• Never patch bundled OpenClaw skill files just to make Linux appear to support macOS tools
• Keep wrapper names explicit, for example imsg-m1 or remindctl-mbp, when multiple Macs may own similar tools
• Log who installed or rotated a wrapper and when
• Keep a rollback path: remove one wrapper, do not tear down the whole node
• If a tool needs more than read or one explicit action, define that permission boundary in the published skill
• If a wrapper depends on a Mac-only GUI permission, verify it explicitly and report a degraded-but-safe state instead of pretending success

Common Presets

Supported presets in scripts/install-preset.sh:

• imsg
• remindctl
• memo
• things
• peekaboo
• brew
• gh

The preset installer resolves the remote binary dynamically. If resolution fails, pass --remote-bin explicitly.

Examples

Wire iMessage Through M1

scripts/install-preset.sh \
  --tool imsg \
  --host agent1@mac-mini.local

Wire Reminders Through MacBook Pro

scripts/install-preset.sh \
  --tool remindctl \
  --host agent2@macbook-pro.local \
  --name remindctl-mbp

Use A Custom Binary

scripts/install-wrapper.sh \
  --name my-mac-tool \
  --host agent2@macbook-pro.local \
  --remote-bin /custom/tools/my-mac-tool

Files

• scripts/install-wrapper.sh: create one secure SSH wrapper for a remote binary
• scripts/install-preset.sh: install wrappers for common macOS tools with dynamic remote resolution
• scripts/verify-node-tool.sh: verify SSH and remote binary availability by path or tool name
• references/publish-pattern.md: how to build a publishable wrapper-aware skill on top
• references/security-model.md: trust boundaries, least privilege, audit trail, and rollback expectations