OpenClaw 网关优雅停机与在途排空（2026）：就绪与存活、有界截止、工具调用收尾、负载均衡对齐、LaunchAgent 信号窗，以及云 Mac mini 上的 macOS 演练

蓝绿发布与每周依赖升级之所以“无聊”，前提是 OpenClaw 网关能在不截断半完成工具调用的前提下离场。到 2026 年，平台团队普遍要求 优雅停机 路径与云原生语义一致：先翻转就绪让负载均衡停止路由新流量，再停止接入循环，在明确截止时间内排空在途 HTTP 与流式工具调用，最后在指标与日志刷出后以零退出码结束进程。本文界定就绪与存活的语义差异，说明如何为长耗时导出设置有界排空而不致饿死其他租户，停机如何与 熔断器 及 死信队列 协同，如何结合 读取超时与挂起诊断 分类慢调用，以及 健康监控 应如何把“正在排空”状态暴露给合成探针。

成本锚点：在专用 Mac mini 上以约 每天 16.9 美元 向 MacHTML 租用环境，预演 SIGTERM 编排便当，比在真实发布中让 launchd 在 三十秒 后升级为 SIGKILL、却仍有多路工具调用占用数据库锁要便宜得多。

信号、launchd ExitTimeout 与系统默认

在 macOS 上，当运维执行 launchctl bootout 或依赖升级触发任务重启时，launchd 会向网关进程发送 SIGTERM。若未提高 ExitTimeout，平台会在固定宽限期后升级为 SIGKILL——许多模板常见为 三十秒，但务必用 launchctl print 核对。Linux 容器的默认窗口不同；混用两类环境而不做桌面级演练，几乎必然在首次大流量发布时翻车。

网关应安装信号处理程序：以原子方式设置 shutting_down 标志、关闭空闲长连接，并线程安全地启动排空计时器。避免在信号处理函数内做重活，把事件投递回主循环，才能保持 TLS 状态一致。

文档化两套预算：对外（负载均衡相信的窗口）与对内（工作池真实需要）。若内部预算大于外部预算，要么延长注销延迟，要么在改停机代码前收紧工具超时。

排空期间的就绪与存活

只要进程仍能推进在途工作，存活 应保持为真；一旦打算拒绝新会话，就绪 应立即为假。许多团队图省事颠倒二者，导致编排层仍把新会话调度到已返回 503 的主机，放大重试风暴。

提供 /readyz 端点，在排空时返回 503 与 JSON，例如 {"draining":true,"in_flight":14,"deadline_ms":12000}，便于健康栈绘制排空曲线。请与 网关健康监控 的可用性语义对齐。

停止接入循环并避免重置风暴

立刻关闭监听套接字可能在在途 TLS 握手上触发 RST。更稳妥的是应用层门控：对新建连接返回 503 并附带 Retry-After: 5，让既有连接完成当前请求。HTTP/2 的 GOAWAY 需要严格顺序：先将最大流 advertised 为零，等待打开流结束，再关闭。

对 WebSocket 工具桥，应在关套接字前发送应用层 server_shutdown 并提示客户端退避，避免所有代理同时扑向下一个实例。

工作池、单工具截止与流式场景

为排空预算分区：墙钟时间的 六成 给常规 REST 工具，三成 给长轮询或流式扇出，一成 给指标抓取等管理钩子。若单一租户独占工作线程，即使在停机阶段也要强制执行每租户并发上限，以免其他租户的工具调用无法收尾。

模型流式输出活跃时，应停止接受新轮次，但允许当前服务端推送泵运行，直到字节完成或子截止（例如 二十秒）先到。对提前截断记录结构化错误 SHUTDOWN_TRUNCATED_STREAM，便于产品侧调参。

负载均衡钩子与 Retry-After

就绪翻转为假后，至少等待一个健康检查周期——常见 五秒——再停止接入。多区域部署若 DNS 仍指向旧实例，应加倍等待。始终输出一致的 Retry-After，客户端幂等故事才能对齐。

四层透传负载均衡下，已建立的 TCP 连接可能在 keep-alive 上复用并排队新 HTTP 请求。为每连接维护代际计数：停机开始后，对旧套接字上的新请求返回 Connection: close，同时仍完成该套接字上的活动请求。

指标、日志与停机后审计

导出计量 gateway_in_flight_total 供抓取，以及计数 gateway_shutdown_events_total{result}，标签取 clean、deadline_exceeded 或 forced_kill。直方图 gateway_shutdown_duration_seconds 应覆盖从就绪翻转到进程退出的整段，便于仪表盘判断 四十五秒 预算是否周周可行。

结构化日志应包含在 macOS 侧配置的等价“优雅期”、观测到的 in_flight 峰值与最慢工具名。与发布工单一并归档，回归时才能同比。

若七日窗口内 clean 占比跌破 百分之九十九 且发布频率上升，通常意味着工具超时悄然拉长或某供应商 SDK 忽略上下文取消。

滚动重启期间的金丝雀权重

滚动重启会放大停机频率。若每台实例每小时都重启，再叠加激进的金丝雀切流， fleet 可能永远达不到稳态。除非合成流量证明余量，否则并发排空实例不宜超过 fleet 的 两成。

在排空期间若五分钟 5xx 超过 百分之一 且任一实例宣告 draining，应自动把权重表回滚到最近已知良好版本并通知发布负责人。

熔断器协同

排空阶段需要更少探测而非更多。与 熔断器 协同：拉长半开间隔，或对已不健康的依赖强制开路，避免在秒针倒计时里把工人浪费在注定失败的上游调用上。

死信生产方与幂等入队

若停机与失败处理入队死信竞态，必须保证入队幂等或可去重；否则 TCP 重试后的重复入队会毒害运维。详见 死信队列设计 中能在进程退出后仍有效的信封字段。

对照：硬杀与优雅排空

场景	硬 SIGKILL	优雅排空
在途数据库事务	可能部分提交	等待或显式回滚钩子
流式模型令牌	句中截断	有界等待与结构化截断标记
发布耗时	更快	典型增加五至四十五秒
运维信任	低	指标证明排空则高

编号上线清单

1. 为 /readyz 增加排空 JSON 并接入仪表盘。
2. 将 ExitTimeout 与内部排空计算对齐并留 十秒 安全余量。
3. 在至少 五十 路合成工具调用持有时集成测试 SIGTERM。
4. 用压测工具验证 HTTP/2 GOAWAY 顺序。
5. 事故复盘模板附带排空时间线表格。

常见问题

混合机队上 systemd KillMode 是否影响 OpenClaw？

应书面记录差异：mixed 与 control-group 决定哪些子进程收到信号。

能否无限排空？

不能——必须有界；无限排空会掩盖卡死工人。请用 挂起诊断 归类慢调用。

Windows 开发笔记本重要吗？

仅当你们交付 Windows 网关；多数设计伙伴仍用 MacBook，macOS 演练依然高价值。

优雅停机是可靠性文化与可度量秒数的交汇。向 MacHTML 以约 每天 16.9 美元 租用 Mac mini，可获得原生 macOS 信号投递、Apple 芯片 浸泡测试余量，以及通过 SSH 与远程桌面观察 launchd 时间线，在触碰客户流量前调好排空预算。