Mac Node Bridge

Bridge macOS-only tools into a Linux OpenClaw gateway via SSH wrappers and connected Mac nodes. Use when a Linux gateway needs to run imsg, remindctl, memo,...

Security Scan

The skill's files and runtime instructions are coherent with its stated purpose (creating SSH-backed wrappers so a Linux gateway can run macOS binaries) and do not request unrelated credentials or install third-party code from the network.

Purpose & Capability

Name/description, SKILL.md, and included scripts all implement the same feature: create small SSH-based wrapper scripts to run a specific macOS binary on a remote Mac. There are no unrelated environment variables, host endpoints, or unnecessary dependencies requested.

Instruction Scope

SKILL.md and scripts only direct the agent/user to verify remote binaries via SSH, create per-tool wrappers, and test them. The instructions explicitly require passwordless SSH and limit scope to single binaries; they do not attempt to read or exfiltrate unrelated files or secrets. The workflow is narrow and documented.

Install Mechanism

This is instruction-only with local shell scripts that write wrapper files into user-controlled directories. There are no downloads from remote URLs or package manager installs; nothing arbitrary is fetched or executed from third-party servers during install.

Credentials

The skill does not require secrets or env vars beyond conventional path variables (OPENCLAW_BIN_DIR, XDG_DATA_HOME, HOME) and optional SSH key/known_hosts arguments passed at install time. Requested data is proportional to the bridge purpose.

Persistence & Privilege

The skill does not request always:true or other elevated platform privileges. It installs per-user wrapper scripts and does not modify other skills or global agent settings.

Assessment

This skill appears to do exactly what it says: create SSH wrappers that execute a single remote macOS binary. Before installing: (1) ensure you control and trust the target Mac(s); (2) use a dedicated SSH key and a non-root account on the Mac; (3) prefer passing --ssh-key and --known-hosts so the wrapper is constrained to a key and known-hosts file; (4) inspect the generated wrapper file to confirm it calls only the intended absolute binary (remote-bin must be an absolute path); (5) run scripts/verify-node-tool.sh first to confirm the remote binary exists; and (6) avoid pointing wrappers at shells or generic remote shells (that would let the wrapper run arbitrary commands). The main remaining risk is operational: these wrappers execute commands on remote hosts you designate—if the remote host or SSH key is compromised, the bridge grants remote execution, so follow the least-privilege and auditing guidance in references/security-model.md.

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 [e-mail] --tool imsg
scripts/verify-node-tool.sh --host [e-mail] --tool remindctl

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

scripts/verify-node-tool.sh --host [e-mail] --bin /custom/path/remindctl

2. Install A Wrapper On The Gateway

For a known tool preset:

scripts/install-preset.sh \
  --tool imsg \
  --host [e-mail]

Or install a generic wrapper:

scripts/install-wrapper.sh \
  --name remindctl-mbp \
  --host [e-mail] \
  --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 [e-mail] \
  --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 [e-mail]

Wire Reminders Through MacBook Pro

scripts/install-preset.sh \
  --tool remindctl \
  --host [e-mail] \
  --name remindctl-mbp

Use A Custom Binary

scripts/install-wrapper.sh \
  --name my-mac-tool \
  --host [e-mail] \
  --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