2026年・OpenClaw ゲートウェイのグレースフルシャットダウン：readiness プローブ、期限付きドレイン、ツール完了、ロードバランサー整合、LaunchAgent の SIGTERM 窓、クラウド Mac mini 上の macOS リハーサル

ブルー／グリーンや週次の依存更新が「退屈な運用」である条件は、OpenClaw ゲートウェイが消える瞬間にツール呼び出しの途中経過を切り捨てないことです。2026年の運用者は、クラウドネイティブと同型のグレースフルシャットダウンを前提にします。readiness を反転してロードバランサーが新規を寄せ付けない状態にし、accept ループを止め、HTTP とストリーミングツール呼び出しを明示的な期限の中でドレインし、メトリクスとログを吐き切ったうえで終了コードゼロで抜ける、という筋道です。本稿では readiness と liveness の意味の違い、長時間の CRM エクスポートを餓死させないドレイン窓の設計、シャットダウンが サーキットブレーカー や デッドレターキュー とどう噛み合うか、読み取りタイムアウトとハング診断 との整合、そして ヘルス監視 がドレイン状態を合成プローブにどう見せるべきかを整理します。

価格の目安として、MacHTML の専用 Mac mini をおおよそ1日16.9米ドルで借り、本番に近い SIGTERM の振る舞いを rehearsal するコストは、launchd が30秒程度で SIGKILL に昇格する現場でツール呼び出しがDBロックを握ったまま落ちるデプロイ事故より安い、という比較になります。

シグナル、launchd ExitTimeout、OS 既定

macOS では launchctl bootout や依存更新によるジョブ再起動の際、launchd がゲートウェイに SIGTERM を送ります。ExitTimeout を上げない限り、一定の猶予の後に SIGKILL へ進みます。多くの雛形では30秒前後と聞くことがありますが、launchctl print gui/$UID/あなたの.plist で実測してください。Linux コンテナは別の既定を持ち、混在フリートでは rehearsal なしに秒数だけ合わせても破綻します。

ゲートウェイはシグナルハンドラで原子的な shutting_down フラグを立て、アイドル keep-alive を閉じ、スレッドセーフにドレインタイマを起動すべきです。ハンドラ内で重い処理は避け、メインループへイベントを渡して TLS 状態を壊さないようにします。

外部の秒数（LB が信じる猶予）と内部の秒数（ワーカーが本当に必要な時間）を文書化してください。内部が外部を超えるなら、バランサ側の登録解除遅延を延ばすか、ツールのタイムアウトを先に短くするなど、シャットダウンコードをいじる前に前提を直します。

ドレイン中の readiness と liveness

liveness は「まだ前進できるか」、readiness は「新規仕事を受けてよいか」です。便宜上これを逆にすると連鎖障害が起きます。readiness を落とさずに 503 だけ返すと、フロントがまだ新規セッションを割り当て、リトライ増幅が起きます。

/readyz で 503 と JSON {"draining":true,"in_flight":14,"deadline_ms":12000} を返し、合成監視がドレイン曲線をグラフ化できるようにします。ゲートウェイのヘルス監視 の uptime 指針とセットで設計してください。

accept 停止と接続リセット嵐の回避

待受ソケットを即閉じると、進行中の TLS ハンドシェイクが RST になりがちです。アプリ層のゲートで 503 と Retry-After: 5 を返しつつ既存接続の現在リクエストは完了させる方が安全です。HTTP/2 では GOAWAY の順序が重要で、最大ストリームをゼロ宣言してから開いているストリームを待ち、最後に閉じます。

WebSocket のツールブリッジでは、ソケットを閉じる前にアプリ層の server_shutdown とクライアント側バックオフのヒントを送り、次ポッドへの雷群を避けます。

ワーカー、ツール別期限、ストリーミング

ドレイン予算の配分例として、標準 REST ツールに壁時計の60%、長時間ポーリングやモデルストリームに30%、メトリクス取得など管理フックに10% を確保する、といった割り当てが現場で説明しやすいです。単一テナントがワーカーを独占するなら、ドレイン中もテナント別同時実行上限を維持し、他テナントの完了機会を残します。

モデルストリーミング中は新規ターンは止めつつ、現在の SSE チャンク送出はバイト完了かサブ期限（例:20秒）のどちらか早い方まで許可します。途中打ち切りは構造化ログ SHUTDOWN_TRUNCATED_STREAM で残し、プロダクト側がプロンプト調整の材料にします。

LB と Retry-After

readiness を落としたあと、バランサのヘルスチェック間隔の少なくとも1回分—多くの構成で5秒—は待ってから accept を止めます。複数リージョンでは DNS TTL が古い宛先へまだ流れるため、その倍程度の余裕を見ることもあります。Retry-After はクライアント SDK のべき等ストーリーと揃え、ブレのない値にします。

レイヤ4パススルーでは、既存 TCP 上の HTTP/1.1 keep-alive が新規リクエストを載せることがあります。世代カウンタで、シャットダウン開始後は古いソケット上の新規リクエストを Connection: close で拒みつつ、そのソケット上のアクティブ1本は完了させます。

メトリクス、ログ、事後監査

ゲージ gateway_in_flight_total と、gateway_shutdown_events_total{result}（clean／deadline_exceeded／forced_kill）を出します。ヒストグラム gateway_shutdown_duration_seconds は readiness 反転からプロセス終了までを測り、45秒予算が週次で現実的かを SLO ダッシュボードで見ます。

構造化ログには、macOS 側に設定した猶予秒数、観測された in_flight ピーク、最遅ツール名を含め、デプロイチケットと突き合わせやすくします。7日で clean が99% を下回りデプロイ頻度が上がっているなら、ツールタイムアウトの緩みやベンダ SDK のコンテキストキャンセル無視を疑います。

ローリング再起動とカナリア

ローリングはシャットダウン頻度を上げます。時間ごとに各インスタンスが再起動し、カナリアの重み付けまで激しいと定常状態に届きません。同時にドレイン中のインスタンスはフリートの20% を超えないよう上限を設け、合成トラフィックで余裕を確認してから緩めます。

ドレイン中に5分 5xx が1% を超えたら、直前の良好な重みテーブルへ戻し、オーナーをページします。

サーキットブレーカー連携

ドレイン中はプローブを増やしたくありません。サーキットブレーカー の half-open 間隔を伸ばす、すでに不健康な依存へはブレーカーを開いたままにする、など、貴重な秒を無駄な上流呼び出しに使わない調整をします。

DLQ とべき等エンキュー

シャットダウンが失敗ハンドラの DLQ エンキューと競合するなら、エンキューはべき等か重複排除が必要です。TCP 再試行後の二重エンキューは運用を汚します。デッドレターキュー設計 のエンベロープ項目と照らし、プロセス終了後も追跡できる形にします。

マトリクス：強制停止とドレイン

シナリオ	強制 SIGKILL	グレースフルドレイン
処理中 DB トランザクション	部分コミットのリスク	待機または明示ロールバック
ストリーミングトークン	文中途切断	有界待機＋打ち切りフラグ
デプロイ遅延	短い	典型で +5〜45 秒
運用の信頼	低い	メトリクスで証明できれば高い

番号付きロールアウトチェックリスト

1. /readyz のドレイン JSON をダッシュボード化する。
2. ExitTimeout を内部ドレイン計算＋10秒の安全余裕に合わせる。
3. SIGTERM 統合テストで合成ツール呼び出しを50本以上抱えた状態を再現する。
4. h2load で HTTP/2 GOAWAY 順序を検証する。
5. ポストモーテムひな型にドレイン時系列 CSV を添付する欄を用意する。

FAQ

systemd の KillMode は OpenClaw に効くか

混在フリートでは mixed と control-group で子プロセスへのシグナル対象が変わる点を文書化してください。

ドレインを無限に延ばしていいか

いいえ。無限ドレインはスタックしたワーカーを隠します。ハング診断 で遅い呼び出しを分類してください。

Windows 開発用ノート PC は関係あるか

Windows 向けゲートウェイを出荷するなら意味がありますが、設計パートナーの多くが MacBook を使う現場では macOS rehearsal が依然として価値が高いです。

グレースフルシャットダウンは、信頼性文化が「測れる秒数」と出会う地点です。MacHTML で借りた Mac mini（およそ1日16.9米ドル）は、ネイティブな macOS シグナル配達、Apple Silicon の soak 余力、SSH／VNC 越しに launchd のタイムラインを眺めながらドレイン予算を詰める、という作業を顧客トラフィックに触れる前に済ませるための現実的な土台になります。