2026 加拿大云 Mac M4 无头 CI 部署 OpenClaw：install-cli.sh、--no-onboard 与 Mac mini 托管 launchd 探针

平台团队把 OpenClaw 迁到加拿大远程 Mac M4 时，常见误区是照搬桌面向导：VNC 里跑完整 openclaw onboard，再指望 SSH 断开后 Gateway 仍在线。CI / 批处理场景需要的是无头（headless）安装链路——官方 install-cli.sh 加 --no-onboard，用预置配置与 launchd 探针替代交互式 TCC。本文只回答「如何在 Mac mini 云 / 云 Mac 构建机上落地可复现的无头 OpenClaw CI」，不重复 SSH 隧道 vs 直连 Gateway 的选型（见 OpenClaw 加拿大 M4：SSH 网关、18789 Token 与 launchd），也不展开带图形 onboard 的 7×24 日志对照（见 远程 Mac 安装 onboard 与 LaunchDaemon 跑稳）。若同一台 Mac mini hosting 还要挂 GitHub Actions runner，请与 云 Mac 自建 macOS runner 分用户、分 launchd 标签，避免抢端口与 Node 版本。

1. 何时必须用无头 --no-onboard，而非交互 onboard

交互式 openclaw onboard 适合首次在有图形会话的 Mac 上完成 TCC（辅助功能、自动化、录屏）。当目标机器是云 Mac 上的 CI 专席、只通过 SSH / 自建 runner 触达、且配置已由内部模板生成时，继续弹向导只会阻塞 pipeline。此时应：

• 用 install-cli.sh 固定 Node LTS 与全局 openclaw CLI semver；
• 加 --no-onboard，把 ~/.openclaw（路径以官方文档为准）从密钥仓库或配置管理同步；
• 单独安排一次性 VNC 窗口完成 TCC（若工作流依赖浏览器自动化），之后仅维护 launchd。

与「远程 Mac 跑稳」文的不同点：本篇交付物是可版本化的 CI Runbook 与探针脚本，而不是桌面操作员手册。

2. install-cli.sh 无头链 vs 完整 onboard：对照怎么选

在Mac mini cloud 供应商处新购席位时，建议第一条 pipeline 就用无头脚本跑通 smoke test，避免「人工 onboard 一次」后无法自动化重建。

3. 无头安装 Runbook：install-cli.sh 与配置注入

以下示例假设专用系统用户 openclaw-ci，与 VNC 管理员分离。在加拿大 M4 云 Mac 上，Node 建议 pin 到 LTS（如 22.x），并与 runner 用户 Node 隔离，防止 nvm 在 launchd 下不可见。

# 以 openclaw-ci 用户 SSH 登录云 Mac
export OPENCLAW_CONFIG_DIR="$HOME/.openclaw"
curl -fsSL https://example.openclaw.dev/install-cli.sh | bash -s -- --no-onboard

# 从 CI Secrets 还原 config（勿提交 Token 到 Git）
install -d -m 700 "$OPENCLAW_CONFIG_DIR"
echo "$OPENCLAW_CONFIG_JSON" > "$OPENCLAW_CONFIG_DIR/config.json"

# 安装 Gateway launchd（若脚本支持）
openclaw gateway install-daemon
openclaw doctor --non-interactive

要点：

1. 幂等：workflow 应能重复执行；已安装时脚本应快速 no-op 或对齐版本。
2. semver 锁：在 Runbook 记录 openclaw --version 与 config schema 版本，升级走变更窗。
3. 磁盘：pnpm / npm 缓存放独立卷或 $HOME/.cache，与 Derived Data 分区，便于 Mac mini hosting 快照策略。

4. launchd 健康检查：进程、端口与日志三角

无头场景下「Gateway 看起来在跑」往往只验证了 curl。生产探针应覆盖 launchd 状态、监听地址与日志关键字。推荐每 5 分钟 cron 或 GHA scheduled workflow 执行：

#!/bin/bash
set -euo pipefail
LABEL="ai.openclaw.gateway"
launchctl print "gui/$(id -u)/$LABEL" | grep -q 'state = running'
lsof -nP -iTCP:18789 -sTCP:LISTEN | grep -q openclaw
curl -sf -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  http://127.0.0.1:18789/health | grep -q '"ok":true'
tail -n 50 ~/Library/Logs/openclaw/gateway.log | grep -Ei 'sharp|EADDRINUSE|401' && exit 1 || true

plist 必须使用绝对路径调用 openclaw，并在 EnvironmentVariables 中显式设置 PATH=/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin。launchd 不读取交互式 ~/.zprofile，这是Mac mini 云上最常见的「SSH 手动能跑、daemon 起不来」根因。

5. 探针结果矩阵：绿 / 黄 / 红怎么处置

黄色持续超过 24 小时应视为发布阻塞：无头 CI 依赖可预测 Gateway，间歇性失败会在 agent 侧放大为整批任务超时。

6. sharp 原生模块：Apple Silicon 云 Mac 上的高频坑

OpenClaw 依赖链里的 sharp（libvips 绑定）在 M4 arm64 上若 Node 大版本或安装用户不一致，会出现 Cannot find module '../build/Release/sharp.node' 或架构不匹配。无头 CI 不能在失败时才第一次装依赖——应在镜像化阶段预编译。

6.1 典型错误与修复

• 用户不一致：root 跑 npm i -g，openclaw-ci 跑 daemon → 对该用户重装 sharp 或全局 CLI。
• Node 升级未重建：升级 Node 后执行 npm rebuild sharp 或重装 openclaw CLI。
• Rosetta 混用：确保 plist 与 CLI 均为 arm64；file $(which node) 应显示 arm64。
• 离线缓存：在Mac mini cloud 构建机预下载 sharp 二进制，避免 CI 每 job 拉 GitHub release。

node -p "process.arch + ' ' + process.version"
npm ls sharp --global 2>/dev/null || true
npm rebuild sharp --foreground-scripts
openclaw doctor 2>&1 | tee /tmp/openclaw-doctor.log
grep -i sharp /tmp/openclaw-doctor.log && exit 1 || echo "sharp OK"

若 doctor 仍报 sharp，优先对齐 Node 与 CLI 安装渠道（同一 install-cli.sh 产物），不要混用 Homebrew Node + npm 全局 CLI 的旧组合，除非 plist 已写死两套路径。

7. Gateway 18789 在 CI 中的边界与 Token 轮换

无头 pipeline 调用本地 Gateway 时应坚持：127.0.0.1:18789 + Bearer Token，禁止把端口暴露到公网。Token 放 CI Secrets（如 OPENCLAW_GATEWAY_TOKEN），轮换时先写新 Token 到 config，reload daemon，再废旧 Secret。与 SSH 转发方案相比，本机回环延迟最低，适合同一云 Mac 上 runner 与 Gateway 共机；跨机调用请回到 SSH 网关文。

workflow 中建议显式超时与重试：Gateway 冷启动可能需 10–30 秒，探针失败不应立即触发 destructive reinstall，应先 launchctl kickstart 一次。维护窗内升级 CLI 时，务必在 Runbook 写清回滚：保留上一版 openclaw 二进制路径与 config 快照，探针变红可在十分钟内切回旧版本，避免 agent 队列长时间空转。

8. 无头 OpenClaw 在托管 Mac 上的安全基线

• 专用用户：openclaw-ci 无 admin、无 VNC 登录。
• Secrets：config 与 Token 仅来自 CI vault；磁盘 FileVault 开启。
• 网络：入站仅 SSH / Tailscale；18789 不对 LAN 广播。
• 供应链：pin install-cli.sh checksum；禁止 curl | bash 无校验生产化。
• 审计：gateway.log 保留 14 天，对接日志栈检索 401 / sharp。
• 爆炸半径：tools.profile 遵循最小权限；不可信 fork PR 不得触达生产 Gateway 主机。

无头自动化提升交付速度，也移除了「人眼扫一眼安装 URL」的缓冲。请把安装脚本地址与 checksum 与生产 TLS 证书同等对待；任何未审计的 pipe-to-bash 都应在变更流程中被拒绝。

9. 接入 GHA 或内部 CI 流水线

探针全绿后，再把 OpenClaw 暴露给流水线，建议分四步落地：

1. 从 GitHub Environments 注入 OPENCLAW_GATEWAY_TOKEN，生产环境设审批人。
2. agent job 使用 runs-on: [self-hosted, macos-m4-canada, openclaw] 标签，与签名 / archive job 分离。
3. 在昂贵 LLM 或浏览器步骤前，先跑与 cron 相同的 shell 探针，失败则快速退出。
4. 构建失败时把 openclaw doctor 输出存为 workflow artifact，便于异步排障。

内存规划：24GB Mac mini cloud 上，若同一晚还要跑 xcodebuild archive，当统一内存压力超过 80% 时应暂停 OpenClaw agent 批任务。队列深度告警能避免团队误把「GitHub 变慢」当成根因，而实际是云 Mac 过载。探针除布尔健康外，建议记录 /health p95 延迟；launchd 冷启动 10–30 秒时，过短的 workflow 超时会误杀正常 Gateway。

10. 首周检查清单（加拿大 M4 专机）

1. 选定 Mac mini hosting 席位（建议 24GB/512GB 起）。
2. 创建 openclaw-ci，跑通 install-cli.sh --no-onboard smoke。
3. 注入 config + Token，openclaw doctor --non-interactive 全绿。
4. 安装 launchd，部署绿/黄/红探针与告警。
5. 预检 sharp；锁定 Node + CLI 版本到 Runbook。
6. 与 GHA runner（若有）分用户验证端口不冲突。
7. 记录重建步骤：新购云 Mac 可在 30 分钟内恢复到相同 Gateway 行为。

11. FAQ

--no-onboard 后还需要 VNC 吗？

若 agent 需要浏览器自动化或 TCC，仍需一次性图形会话授权；纯 CLI / API Gateway 可无 VNC 长期运行。

install-cli.sh 与 install.sh 怎么选？

CI 只要 CLI + Gateway 时用 install-cli.sh；需要菜单栏 App 时用完整安装包，不适合无头 runner 重复部署。

探针报 401 但进程在跑？

多为 Token 轮换不同步或 workflow 用了旧 Secret。核对 config 与 Authorization 头，避免代理注入过期 Token。

sharp 只在 launchd 下失败、SSH 正常？

几乎总是 PATH 或用户环境不同。对比 launchctl print 中的 environment 与交互 shell 的 env。

能否在 Docker 里跑 OpenClaw Gateway？

macOS 上 Docker 无法替代原生 TCC / GUI 自动化；Gateway 仍建议原生 launchd，容器仅跑周边工具。

与 GitHub Actions 同机如何排程？

OpenClaw job 与 xcodebuild 错开高峰；内存 > 80% 时暂停 agent 任务，优先保证签名构建。参见 自建 runner 文 的并发标签策略。

Hashvps 加拿大节点适合无头 OpenClaw 吗？

适合需要独享 IPv4、M4 裸金属与 SSH 常驻的 team；选型前确认磁盘档位能否容纳 npm 缓存与 gateway 日志。

升级 openclaw CLI 的标准流程？

维护窗：launchctl bootout → 跑 install-cli 对齐版本 → npm rebuild sharp → doctor → 探针绿 → 恢复 traffic。