OpenClaw Webhook の冪等性とキュー飽和：レンタル Mac mini（2026）
HTTP Webhook は物理的に少なくとも一度（at-least-once）です。SaaS はタイムアウトで再試行し、TLS ミドルボックスはパケットを複製し、あなたの launchd エージェントはリクエスト途中で再起動するかもしれません。OpenClaw をレンタルの Apple Silicon Mac mini上に置き、香港・日本・韓国・シンガポール・米国のいずれかで動かすとき、「ちょうど一度の副作用」はあなたの契約でなければなりません。HTTP 意味論を願望的に読んでも埋め合わせられません。本 2026 ガイドは冪等キー表面、重複排除ウィンドウ、キュー飽和時の挙動（正直な 429 を含む）、そしてオンコールが重複が無害か危険かを証明できる可観測性を定義します。合わせてWebhook／定期とゲートウェイ、秘密と LaunchAgent plist、構造化ログとディスクローテーション、iCloud／同期ブロック QA リスクマトリクス、ゲートウェイ復旧とエージェント再起動を読み、リトライが静かなデータ破損にならないようにしてください。
VmMac はベアメタルと到達性を提供します。重複排除ポリシーはゲートウェイコードとストアレイアウトに残ります。
バースト流量、再配送、そして少なくとも一度という現実
意味のある webhook はインシデント時に5分以内に二度届くと想定してください。GitHub、Stripe、社内イベントバスはストレス下でそう振る舞います。OpenClaw ハンドラは輸送成功（HTTP 200 を返した）と業務成功（変異が一度だけ適用された）を分離しなければなりません。防ぎたい失敗は微妙です：上流は 200 を受け取り、永続化 ACK の前にクラッシュし、あなたのゲートウェイがすでに仕事をキューに入れたあと再試行する——冪等がなければクレジット二重消費、ビルド二重起動、Slack 二重投稿になります。
- ベンダージッター：再試行は人間の反応より速い——手動チケットではなく自動化向けに設計する。
- ローカル再起動：macOS アップデートやゲートウェイ更新は重複ウィンドウを広げる——変更カレンダーに書く。
- 地域対称性：VmMac の各地域で同一意味論——地域ごとの裏技より優先する。
冪等キー契約：ヘッダ、ボディ、スコープ
キーの正典ソースを一つに——Stripe 型 API なら Idempotency-Key、あるいはベンダーイベント ID の署名ハッシュ。必須フィールド欠落は早めに 400 で拒否する。接続ごとに黙ってキーを捏造しない。さもなくばプロセス間で重複排除が非決定的になります。環境ごとの名前空間プレフィックス（stg- と prd-）でキーを束ね、ステージングのリプレイが本番台帳と衝突しないようにします。
重複排除ウィンドウと耐久ストアの置き場所
単一ノードゲートウェイの現実解はローカル NVMe 上の SQLite：トランザクション挿入で「見たキー」チェックを原子化できます。選ぶストアが何であれ、Desktop／Documents コンテナの外に置き、同期ツールが触りうるパスからも外す——同期ブロック QA マトリクスと同じ規律です。大きな更新では DB ファイルをローテし、サイズを週次 SRE レビューで記録してください。
キュー深度、ワーカープール、HTTP 429 バックプレッシャー
キュー深度が SLO を超えたとき 500 を返すと、上流はもっと強く叩く習慣を学びます。規律ある 429 と Retry-After は飽和を協調シグナルに変えます。社内開発者ポータルに振る舞いを公開し、上流オーナーが意図的であることを知らせましょう。飽和イベントにはドロップ対遅延のメトリクスを添える——ポストモーテムでは二つの曲線が別物を語ります。
| シグナル | 呼び出し側の解釈 | いつ使うか |
|---|---|---|
429＋Retry-After |
協調バックオフ | 閾値超えだがホストは健全 |
503 短文 |
ジッター付き再試行 | 依存障害（DB ロック） |
401／403 |
秘密の再試行を止める | トークンローテ失敗 |
launchd ThrottleInterval、プロセス上限、並行キャップ
LaunchAgents はバースト後にキューが空くより速く蘇ることがあります。ThrottleInterval を最悪ケースのハンドラ時間に揃え、並行 Node ワーカーにハード上限を課してファイル記述子と SQLite ロックを予測可能に。エージェントが OpenClaw の HTTP リスナとポートを共有する場合は、ゲートウェイ復旧のポート衝突ガイダンスを再利用し、再起動後に各リスナが重複排除状態を独占したと誤認するのを防ぎます。
相関 ID、構造化ログ、メトリクス
インバウンド HTTP 接続ごとに相関 ID を一つ発行し、キューエントリ、子プロセス、ゲートウェイが行う外向き呼び出しへ伝搬させます。その文字列が「この重複は無害だったか？」を数分で答えられる理由です。JSONL フィールドは構造化ログで約束したスキーマと揃え、ダッシュボードを地域間で移植可能にしてください。
五地域一貫性：香港、日本、韓国、シンガポール、米国
毎週各地域で同じ合成リプレイを走らせ、同一キーの重複イベントを注入して副作用が一度だけであることを断言します。乖離はだいたい時計の前提か異なる SQLite pragmaであって、謎のネットワーク幽霊ではありません。地域設定は同一リポジトリリビジョンに置き、ドリフトはコードレビューで見えるようにします。
FAQ：OpenClaw と webhook 冪等性
重複排除は再起動をまたぐべきか？ はい——揮発 RAM 集合は macOS アップデートがホストを再起動した瞬間にベンダー保証を失う。
429 を避けて垂直スケールだけで済ませられるか？ 金属は助けるが、バーストは組織成長に対して超線形——シグナルは依然として価値がある。
鍵ローテの所有者は？ あなたのプラットフォームチーム。VmMac はアプリケーション秘密をローテしない。
なぜ 2026 年も Mac mini M4 がキュー重いゲートウェイに合うか
Apple Silicon Mac mini は SQLite バックのキューとローカル扇拡散に対して単一テナントスループットが読みやすく、騒がしい隣人もいません。地域ごとにレンタルすれば上流 SaaS の出口近くにゲートウェイを置きつつ重複排除意味論は同一のまま。新しい webhook ソースごとに冪等を完了の定義へ組み込めば、リトライはテレメトリになり、恐怖ではなくなります。
