AI / 自动化 2026年4月17日

2026-04-17 无头租用云 Mac 上的 OpenClaw onboard 与 install-daemon

MacXCode 技术团队 2026年4月17日 约 15 分钟阅读

OpenClaw 在 2026 的 npm 发行版继续强调 CLI 优先：全局安装、运行 openclaw onboard，由工具为网关生成 LaunchAgents。在一台只能通过 SSH 操作的租用 Apple Silicon Mac 上，主路径仍然顺滑——直到交互假设有 GUI、环境变量缺失，或 Node 落后上游建议两个大版本。本 2026-04-17 指南覆盖前置条件、固定版本安装、守护进程创建与在 HK / JP / KR / SG / US 节点上的验证。启动稳定后，继续阅读 网关升级与回滚、通过 launchd 管理密钥 与 健康探针，再暴露 webhook。另建议把首次成功的 openclaw --version、node -v 与 plist label 记录进 CMDB，后续排障可以直接对照。

前置条件：账号、端口与策略

  • 出站 HTTPS：模型与通道端点必须在你的区域可达；为企业租户记录允许清单。
  • 本地绑定：默认网关监听常在 127.0.0.1:18789；公网流量请配合 nginx 入口。
  • 用户上下文：在与 CI 或运维会话相同的 POSIX 用户下安装；避免拆分 home 目录。

若主机由多名工程师共享，请把 API Key 的轮换责任写清：谁生成、谁写入 plist、谁验证 curl。无头环境最怕“某人本机 export 过但 CI 没继承”。

Node 版本固定（22 LTS 对比 24）

近期 OpenClaw 构建的上游说明倾向在可用环境使用 Node 24，并以 Node 22.16+ 作为支持下限。在 macOS Sonoma / Sequoia 构建机上可用组织批准的安装器（fnm、nvm 或 pkg），但务必在基础设施即代码里固定版本。把 node -v 与 npm -v 与脱敏后的 openclaw.json 放在同一制品包中。

node -v && npm -v && which node

不要混用 系统 /usr/bin/node 与 Homebrew Node——launchd 继承的 PATH 很小；必要时在 plist 的 EnvironmentVariables 中写绝对路径。

SSH 会话与非交互纪律

在 onboard 之前导出供应商密钥：许多流程会读取 OPENAI_API_KEY 风格变量或自定义桥接令牌。完全非交互安装时，把 export VAR=… 与 openclaw onboard 放在同一次 shell 调用，或 source 权限为 0400 的安全点文件。若 CLI 仍提示交互，请查阅对应 semver 文档中的 --yes 类开关。

对长时间会话，记录 SSH_TTY 与 LC_ALL，避免编码差异导致日志乱码，进而误判守护进程状态。

安装 CLI（固定版本，避免漂移）

生产环境应匹配显式版本号，例如 npm 元数据中的 2026.4.x，而不是区域第一台主机上的裸 @latest。

npm install -g openclaw@2026.4.15

安装后运行 openclaw --version，把标准输出写入 CMDB——未来差异对比依赖这条基线。

运行 openclaw onboard --install-daemon

onboard 子命令通常会引导模型选择、工作区默认值与守护进程安装。在无头主机上，如安全基线要求特定 ACL，请预先创建 ~/.openclaw 并校正属主。当 --install-daemon 完成后，你应在 ~/Library/LaunchAgents 看到 plist 引用，label 可能类似 ai.openclaw.gateway（具体名称随版本变化——务必阅读工具输出的路径）。

信号 健康 异常
CLI 退出码 0，并出现 “installed daemon” 摘要 非零，且在 plist 目录出现 EACCES
文件 已创建 plist 与日志目录 仅有部分 ~/.openclaw，但缺少 LaunchAgents 项
端口 curl 访问文档中的 localhost 端口成功 陈旧进程导致地址占用

launchd 校验与重复检测

按你的 macOS 版本使用 launchctl bootstrap gui/$UID … / kickstart 等模式为当前无 GUI 会话引导 Agent。随后立即运行 openclaw doctor，详见 重复 LaunchAgents 恢复——在未 unload 的情况下重复执行 onboard 很容易堆叠重复 plist。

健康检查、日志与何时加 Nginx

使用 就绪探针 中的轻量 curl：循环请求 127.0.0.1 直到 HTTP 200，再挂 nginx TLS。首次通道握手时 tail ~/.openclaw/logs（若设置 OPENCLAW_STATE_DIR 路径可能不同），尽早捕获鉴权配置错误。

第一台节点稳定后，通过 定价 把手册复制到次要区域，而不是让单台 Mac 同时扛重 Xcode lane 与常驻 AI 网关。若需要 mesh 访问而非公网入口，在开放端口前先阅读 Tailscale 网格。容器化取舍见 Docker 与原生 npm。

Teams comparing terminal agents: see our Codex CLI 对比 Claude Code M4 评测 (Terminal-Bench 77.3% 对 65.4% 的租用机构建机对比).

常见问题：云 Mac 首次安装

问题 答案
能在 tmux 里运行 onboard 吗？ 可以——确保加载相同环境块；tmux 窗格常忘记 launchd 注入的变量。
18789 端口冲突怎么办？ 停止旧网关、unload 陈旧 plist，然后重跑 doctor；自定义端口写入 nginx upstream。
Docker 是否更简单？ 取舍不同——见 Docker 对比原生；本文聚焦 npm 原生守护进程。

结论：固定 Node、固定 npm semver、在 SSH 前导出密钥、干净地安装守护进程一次，用 doctor + curl 验证，再用升级与入口手册加固——不要反过来。

OpenClaw + Xcode 侧车的专用 M4

SSH 优先 · HK · JP · KR · SG · US