租赁云 Mac 上的 openclaw doctor、重复 LaunchAgents 与网关恢复（2026）
2026 年上游 OpenClaw 在 macOS 上可能注册不止一个带相似标签的 launchd 作业——尤其在团队混用桌面应用路径与CLI 网关安装时。在 港/日/韩/新/美 的 7×24 租赁 Apple Silicon 云 Mac 上，这会表现为面板抖动、修改 ~/.openclaw/openclaw.json 后行为仍“像旧的”、或 18789 端口被陈旧二进制占用。openclaw doctor 是官方推荐的第一步排障；本文把 doctor 输出整理成可重复的收敛手册。升级后请配合 升级与回滚、与 网关故障排查、以及 launchd 环境变量与 API 密钥 一起使用。
哪些症状像“重复服务”
openclaw gateway status与launchctl list不一致。- 编辑
~/.openclaw/openclaw.json后运行时行为不变。 ~/Library/LaunchAgents/下有两个 plist，ProgramArguments指向不同 OpenClaw 路径。
~/.openclaw 放在 iCloud Drive / Dropbox —— 文件锁会破坏代理状态；请放在租赁机本地 NVMe。
重复 LaunchAgent 的根因
重复很少“随机出现”，通常来自安装路径随时间变化。长租裸金属上常见序列：
- 升级未卸载：npm
-g升级后，旧 app bundle 仍注册网关 plist。 - 多账户试验：
admin与builder各留一份 LaunchAgent。 - 自动化重复执行：Ansible/脚本每次运行都追加 plist，而非幂等声明。
- 手工复制：按网文把 plist 丢进
LaunchAgents却未 unload 旧 Label。
| 信号 | 可能的重复模式 | 忽视的风险 |
|---|---|---|
| 18789 端口 PID 来回变 | 两个网关在启动时争抢 | Webhook 失败；配置写到一半 |
CPU 空闲但 launchctl list 有两个 OpenClaw 标签 |
一个代理崩溃，另一个未清理 | 与预期 openclaw.json 静默漂移 |
~/.openclaw/logs 体积暴涨 |
双代理都在 debug 记日志 |
512 GB 盘片压力 |
把「每台主机只允许一种权威安装源」写进内部 SLO：自助脚本与人工排障若在 港/日/韩 多时区交接中交替执行 gateway install，很容易在凌晨把第二份 plist 悄悄加回。维护窗口内冻结变更，并在工单模板里强制附上最近一次 doctor 全文与时间戳。
ProgramArguments 是否仍指向预期二进制。若与 磁盘套餐 扩容同步进行，请单独记录一次基线 doctor，避免把磁盘迁移误判为网关故障。
以 openclaw doctor 为基线
openclaw doctor
将标准输出写入 CI 日志或工单。doctor 通常会标出路径、版本偏差、launchd 注册问题——生产代理机上警告应视为阻断项。
在任意 gateway install 或大版本升级前后各跑一次 doctor：对比两次输出可知 launchd 是否真正收敛。建议把文本存到日期目录（如 ~/ops/openclaw/2026-04-09-pre.txt），便于在数月 7×24 运行中做回归比对。
若 doctor 提示陌生修复参数，请在工单中固定 OpenClaw 版本号并对照上游发行说明——云 Mac 往往比笔记本慢一个版本，利于复现也可能因语义变化踩坑。
检查 LaunchAgents
ls -la ~/Library/LaunchAgents/ | grep -i openclaw
逐个打开 plist，记录 Label、ProgramArguments、EnvironmentVariables。若同时存在 ai.openclaw.gateway 与 ai.openclaw.mac 风格标签，需选定本机唯一安装模式（原生 npm 或 app bundle）。
留意 WorkingDirectory 与注入的 PATH：重复实例常只差 Node 路径（/usr/local/bin vs ~/.nvm/versions/...），就足以分叉运行时。请在运维手册用三列表格记录差异，避免下一轮值班又把第二份 plist 加回来。
收敛顺序（尽量缩短中断）
- 若有外部自动化依赖该网关，先公告维护；
bootout期间监听中断常见 30–120 秒。 - 对每个非权威 Label 执行
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/<duplicate>.plist（若使用不同 bootstrap 域请相应调整）。 - 用
launchctl print gui/$(id -u)/<label>确认仅剩预期作业。 - 将退役 plist 移到
~/Archive/LaunchAgents-2026-04-09/而非直接删除，便于回滚比对。 - 对选定模式只执行一次
openclaw gateway install（或 doctor 建议的修复）；避免同一分钟内重复跑安装脚本。 - 如需则
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/<canonical>.plist，再反复运行 doctor 直至干净。
验证网关健康
lsof -nP -iTCP:18789 | grep LISTEN—— 应只有一个 PID 监听。openclaw gateway status—— 与上次绿发布的基线输出对比。openclaw logs --follow（采样 200 行）——对照 安装指南 基线。- 若暴露健康检查路由，可从 日本或美国 另一台 MacXCode 节点探测，确认跨区域可达性与防火墙策略一致。
网络、防火墙与 18789 端口
租赁云 Mac 可能位于提供商 ACL 或你们安全组之后。必须为需要访问的子网显式放行 OpenClaw 网关监听的 TCP 18789——无论是 韩国 的 CI、运维笔记本，还是反向代理 VM。
若在网关前用 nginx/Caddy 终结 TLS，请记录链路跳数：X-Forwarded-* 不匹配会让健康检查打到错误上游，看起来像“重复网关”。在 内部帮助页 维护唯一的「公网 URL → 后端端口」说明，并在主机 ~/ops/README.txt 镜像一份。
nc -vz host 18789，安静内网路径应在 < 5 ms 级完成；若数秒级，多半是过滤或不对称路由，而非 OpenClaw 本身。
决策矩阵：一机一模式
| 目标 | 优先 | 避免 |
|---|---|---|
| 可脚本化 CI 运维 | npm/CLI 网关 + 单一 LaunchAgent | App 与 CLI 同时管网关 |
| 以 GUI 试验为主 | 官方 app 路径；关闭 CLI 重复项 | 并行多套网关安装 |
| Docker 隔离 | 仅在 Compose 内跑网关；宿主机不重复 | 宿主机 LaunchAgent 与容器同绑 18789 |
裸金属 Mac mini M4 为何更省事
排查重复 LaunchAgent 是强状态工作：读 plist、对比环境、循环重启守护进程直到 doctor 干净。Mac mini M4 配本地 NVMe 可减少超卖虚拟机的快照/重启歧义，launchd 语义与桌面机一致。MacXCode 在香港、日本、韩国、新加坡、美国 提供节点，可把网关放在靠近 API 消费者或合规边界的位置，同时保留 SSH 自动化与偶发 VNC 图形验证。
租用也便于低成本跑金丝雀主机：从生产克隆 plist 策略，先在新版本验证再推广。容量不足时在 定价页 扩容磁盘或加第二台节点，而无需提前数周采购机器。
结语：把 openclaw doctor 当作权威提示，再机械地去重 LaunchAgent 并复检监听。稳定裸金属让这套演练成本很低——详见 套餐 与 帮助。