Mac Node Bridge

当你的网关运行在 Linux 上，而实际工具部署在 Mac 节点上时，请使用此技能。

该技能不会修补已打包的 OpenClaw 技能。它会显式创建 SSH 封装器（wrapper）及验证步骤，使 Linux 网关能够以可发布、可重复、可审计的方式调用连接 Mac 节点上的 macOS 二进制程序。

适用场景

• imsg、remindctl、memo、things、peekaboo 或其他仅支持 macOS 的 CLI 工具
• 仅存在于 Mac 节点、通过 Homebrew 安装的业务工具
• Linux 网关 + 一个或多个 Mac 节点，并希望构建一条稳定的远程执行路径
• 面向 ClawHub 的技能，需干净地适配 Mac 目标，而非修改已打包的 Linux 假设逻辑

不适用场景

• 本应直接安装在网关上的 Linux 原生 CLI 工具
• 仅涉及 UI 配对的问题
• 你无法从网关向 Mac 节点建立免密 SSH 连接
• 通过打补丁方式强行让已打包的 OpenClaw macOS 技能在 Linux 上显示为“绿色”（即正常通过）

前提条件

• Linux 网关可免密 SSH 登录目标 Mac 节点
• 目标 Mac 节点上已存在待调用的远程二进制文件，且具备可执行权限
• Mac 节点已授予所有必需的 macOS 隐私权限（如辅助功能、全盘访问等）
• 你已明确指定应由哪台 Mac 托管该工具

路径规则

默认使用动态路径解析。

• 封装器安装目录默认依次查找：OPENCLAW_BIN_DIR → XDG_DATA_HOME/openclaw/bin → HOME/.openclaw/bin
• 预设安装（preset install）会通过 command -v、远程 brew --prefix 及常见 Homebrew 前缀，动态解析远程二进制路径
• 仅在你有明确需求覆盖默认行为时，才使用 --target-dir 或 --remote-bin

信任模型

该技能基于以下假设：

• Linux 网关作为编排中心（orchestrator）
• 每台 Mac 节点是独立可信的执行面（execution surface）
• 跨主机访问必须严格限定范围、显式声明、可逆操作

请围绕以下原则进行设计与部署：

• 使用强约束、细粒度的凭证与按节点划分的信任机制，避免单一宽泛共享密钥
• 要求 Mac 端在网关接受编排指令前，主动完成身份认证
• 每个封装器仅授予其所需执行的最小权限动作
• 记录所有跨主机的初始化、验证与部署步骤
• 当某台 Mac 不可用时，采用软失败（fail soft）策略，不得导致整个系统崩溃

在发布或扩展该技能前，请务必阅读 references/security-model.md。

工作流程

1. 选定托管 Mac

默认推荐模式：

• M1：用于始终在线的服务，例如 imsg
• MacBook Pro：用于较重的交互型或业务型工具

若尚不确定，请先验证：

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

若工具不在常规 shell 路径或 Homebrew 默认路径中，请显式传入完整路径：

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

2. 在网关上安装封装器

对于已知预设工具：

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

或安装通用封装器：

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

仅在需要非默认目录布局时，才覆盖封装器安装路径：

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

3. 验证封装器

"${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

若封装器可正常运行，但已打包的 OpenClaw 技能在 Linux 网关上仍显示为灰色（gray），属预期行为。请采用基于封装器的工作流，或发布支持封装器的技能，切勿修补 OpenClaw 核心代码。

4. 发布支持封装器的技能

当基于该桥接机制构建新的 ClawHub 技能时：

• 通过可配置的路径契约（path contract）调用封装器，而非硬编码用户专属绝对路径（如 $HOME）
• 明确文档化该工具由哪台节点托管
• 将密钥、令牌等敏感信息存放于节点或网关配置中，而非技能文件夹内
• 将封装器视为稳定对外接口（stable contract）

在将临时封装器升级为公开技能前，请务必阅读 references/publish-pattern.md。

安全规范

• 尽可能为网关到节点的封装器使用专用 SSH 密钥
• Mac 节点上应使用非 root 用户账户
• 优先为每个节点上的每个工具单独创建封装器，而非构建一个无限制的通用 Shell 桥接
• 禁止在技能文件夹中存储 API tokens、应用密钥（app secrets）或 OAuth cookies
• 禁止为让 Linux 表面支持 macOS 工具而修补已打包的 OpenClaw 技能文件
• 当多台 Mac 可能托管同类工具时，应使用明确命名的封装器（如 imsg-m1 或 remindctl-mbp）
• 记录封装器的安装者、轮换者及对应时间戳
• 保留回滚路径：仅移除单个封装器，不得破坏整台节点
• 若工具需要超出只读或单一显式动作的权限，应在发布的技能中明确定义该权限边界
• 若封装器依赖 Mac 独有的 GUI 权限（如辅助功能），须显式验证；验证失败时应报告“降级但安全”的状态，而非伪装成功

常用预设项

scripts/install-preset.sh 中支持的预设项：

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

预设安装器会动态解析远程二进制路径。若解析失败，请显式传入 --remote-bin 参数。

示例

通过 M1 接入 iMessage

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

通过 MacBook Pro 接入 Reminders

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

使用自定义二进制文件

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

相关文件

• scripts/install-wrapper.sh：为远程二进制文件创建一个安全的 SSH 封装器
• scripts/install-preset.sh：为常见 macOS 工具安装封装器，支持动态远程路径解析
• scripts/verify-node-tool.sh：通过路径或工具名验证 SSH 连通性与远程二进制可用性
• references/publish-pattern.md：如何在其之上构建可发布的、支持封装器的技能
• references/security-model.md：信任边界、最小权限原则、审计追踪及回滚预期