在 macOS 上，OpenClaw 网关通常由 launchd 托管。运维人员——有时甚至 Agent 自己——会在仍依赖该网关的会话里执行「重启网关」。该模式可能在发起 RPC 仍附着时就 bootout 作业，从而出现「直到有人用另一条 Shell 登录才恢复」的真实故障。本手册说明原因、给出安全/危险行为对照表、列出六条可执行步骤与数值护栏，并链到更深入的恢复与并发文章。
变更前请先阅读 LaunchAgent 网关恢复 与 交互式对话与长任务并发，避免重启与重编译互斥窗口相撞。首次安装仍以 安装与部署全指南 为准。账号类问题见 帮助；若要把网关与 CI 拆到两台主机，见 定价。
故障模式：launchd 下的「自斩首」
把网关同时视为服务端与你所执行命令的依赖。当 Agent 通过同一 RPC 通道调用 openclaw gateway restart（或等价封装）时，launchd 可能在握手完成前卸载作业，发起 CLI 以传输错误退出，且无人保证随后一定发生健康的 bootstrap——在仅暴露 SSH 的无头主机上尤其隐蔽。
- 症状 A：执行重启同一秒内
gateway status从运行中变为缺失。 - 症状 B：日志里 launchd unload 行与 RPC 断开错误相邻。
- 症状 C：外部 HTTP/TCP 健康检查超时数分钟，而用户会话尚未启动 GUI。
矩阵：谁可以重启网关
| 角色 | 典型上下文 | 结论 | 更安全替代 |
|---|---|---|---|
| 人类运维（第二条 SSH） | screen 或普通 ssh | 首选 | 按文档 bootout/bootstrap 并留存日志 |
| OpenClaw 内自动化 Agent | 处理聊天时的工具调用 | 避免重启 | 出票；由外部编排器在互斥后重启 |
| 定时 LaunchAgent | 夜间漂移修复 | 可用（独立 plist） | 与高峰聊天错峰，参见 定时任务对齐 |
| 同机 CI 作业 | 流水线步骤「弹一下网关」 | 不推荐 | 独立管理队列与凭证 |
第二矩阵：重启前检查表
| 检查项 | 通过标准 |
|---|---|
| 监听归属 | 仅一个 PID 匹配配置端口族；记录 PID 供回滚笔记 |
| 日志盘空间 | 状态与日志所在卷至少保留 8 GB 空闲，避免写半截失败 |
| 与长任务互斥 | 无工作区作业占用你为网关维护定义的编译互斥层级 |
| 鉴权令牌连续性 | 客户端可从磁盘重载令牌，无需交互 GUI 授权 |
每次应记录的运维数字
- 冷启动预算：
bootstrap后最多等待 90 秒 再判失败；若有杀毒或「完全磁盘访问」弹窗可更长。 - RPC 探测间隔：首分钟每 5 秒 探测，之后指数退避。
- 并发管理动作：每台主机同时仅 一条 变更网关的作业，避免并行改 plist 找不到根因。
无头提示：若怀疑 GUI 权限对话框，可临时通过 VNC 点一次，再回到纯 SSH 运维。
六条主机步骤（HowTo 文字展开）
- 停止通过故障网关继续下命令。再开一条到同一 Mac mini M4 的 SSH，该会话不得依赖即将被回收的 RPC。
- 取证：status、近期日志、你认为权威的 plist 路径——对照 配置漂移 指南。
- 用
lsof等验证监听，避免实验室多实验共享一机时bootout错 PID。 - 按当前 macOS 版本使用合适的 launchd 卸载语义，随后从磁盘 bootstrap，确保 EnvironmentVariables 与 WorkingDirectory 生效。
- 在外部 Shell 探测健康，RPC 成功后再让聊天客户端重连。
- 写一行事故记录：时间、原因、聊天/CI 是否受影响——日后与 限流 指标关联会极省事。
常见问题
能用 Ansible 自动化重启吗？
可以，前提是控制连接不经过你要重启的网关进程。把网关当数据库：从编排面 bounce，而不是从客户端查询里 bounce。
开发/生产多套网关怎么办？
分离 plist、端口与状态目录；文档写清哪个 Label 对应哪套环境，避免 bootout 打错标签。
何时应拆主机？
当聊天 SLO 与 CI 抢占在互斥分层后仍冲突——增购第二台 NodeMac 专用 Mac mini M4，而不是把不兼容生命周期叠在同一张 launchd 图上。
稳定的 OpenClaw 与稳定构建共享同一硬件叙事：专用 Mac mini M4 提供 Apple Silicon 性能与 原生 macOS，SSH 做无头维护，需要 UI 授权时用 VNC，并可在 香港、日本、韩国、新加坡、美国 选择节点让值班人员更靠近凌晨要唤醒的机器。租用而非采购 使「网关专用第二台机」在成本上可行——当本手册证明你不该把实验 Agent 与生产聊天叠在同一 plist 图时，先到 定价页 按区域选型。