定時ジョブ・受信Webhook・CIコールバックとべき等性
小さなチームはすでにOpenClaw Gatewayを運用していますが、Slack型のIMを置かずとも定時チェック、受信Webhook、CIの結論で自動化を回したい場面は多くあります。本稿では3種のトリガー分類、認証とべき等性の対応表、オンコール用wikiに貼れる6ステップのRunbookを定義します。末尾では本番でよく使う数値の目安と、ホスト型Macノードが運用負荷を下げる条件を整理します。
チャットチャネルには「誰が」「どのスレッドで」話したかという暗黙の文脈があります。純粋なHTTPとcronだけの流れでは、最初から契約をコード化しないとそれが失われます。本番前に次の失敗モードを確認してください。
重複配信が副作用を二重化する：CI基盤やWebhook中継はタイムアウトで再送することがあります。べき等性キーと重複排除ウィンドウがなければ、同一ジョブ成功が二度実行される恐れがあります。
認証が弱い：秘密URLはログやプロキシから漏れます。最低でもヘッダーシークレット、HMAC、またはmTLSへ移行してください。
cronがメンテナンスと衝突する：常時稼働ノードをパッチ中にcronが走ると、ハンドラが半初期化状態で動くことがあります。
リージョン横断の順序神話：先に受信したことが先に発生したことではありません。イベント時刻と単調なシーケンスを運びましょう。
観測性が薄い：リクエストID、上流ジョブID、べき等性の指紋がなければ、チケットとログを対応付けられません。
トリガーはプロダクト要件のように扱いましょう。レイテンシ感度、一貫性、許容ドリフトがcron、Webhook、CIコールバックのどれかを決めます。
| トリガー | 典型的な用途 | 強み | 主なリスク |
|---|---|---|---|
| 定時ビート | ヘルススイープ、日次サマリー、一時ファイル掃除 | 負荷が予測しやすく、運用が単純 | 実イベントから切り離される。メンテ中は一時停止 |
| 受信Webhook | チケット連携、承認、監視のHTTPエクスポータ | 業務イベントにほぼリアルタイムで追従 | 重複、なりすまし、TLSとプロキシの複雑さ |
| CI終端コールバック | ビルド後署名、リリースゲート | 成果物との結びつきが強い | プラットフォーム再試行が不透明。ペイロード版ずれ |
実務での組み合わせ
副作用を一度だけ起こすならWebhookまたはCIコールバックにべき等ストレージを併用します。読み取り専用の集計にはcronを残します。Gatewayを公網に晒す場合はTLS終端とリスナーの絞り込みをエッジで行い、基準チェックはインストールとGatewayトラブルシュートのチェックリストに従ってください。
順番に実行し、検証してからトラフィックを広げます。シークレット名はVault方針に合わせてリネームしてください。
契約を固定する：JSONにevent_time、source、job_id、idempotency_key、payload_versionを必須とし、版のない未知ペイロードは拒否します。
エッジで認証する：リバースプロキシでAuthorizationベアラまたはHMACを検証し、IP許可リストを併用。Gatewayは内部ホップのみ信頼します。
べき等ストレージを足す：idempotency_keyを主キーにしTTL（CI向けに多くは24〜72時間）。重複POSTは同一の業務応答を返します。
メンテ中はcronをゲートする：フラグファイルまたはKVゲート。メンテ有効時は早期終了とハートビートログを出します。
観測性の三点セットを配線する：入口ごとにrequest_idを生成し応答ヘッダに返し、ログにはjob_idとハッシュ化したべき等性キーを残します。
再試行をカオス注入する：同一POSTを3回、30秒上流断を挟み、復旧後に副作用の二重化がなくページングが正しいことを確認します。
curl -sS -X POST "https://gateway.example.internal/hooks/ci" \
-H "Authorization: Bearer ${HOOK_SECRET}" \
-H "X-Idempotency-Key: ${CI_JOB_ID}-${CI_CONCLUSION}" \
-H "X-Request-Id: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"payload_version":1,"job_id":"'"${CI_JOB_ID}"'","conclusion":"success"}'
社内専用と公網入口では脅威モデルが異なります。レビューアを揃えるために表で共有してください。
| パターン | 適合 | 必須設定 |
|---|---|---|
| 共有シークレット＋TLS | プライベートネットまたはゼロトラストトンネル | シークレットをローテーション。応答に秘密を返さない |
| HMAC署名 | 公網Webhook、上流が多い | タイムスタンプ窓はおおよそ±300秒。定時間比較 |
| mTLS | エンタープライズCIからコントロールプレーン | 短命リーフ証明書のローテーションと失効 |
べき等性キーの形。 {source}:{stable_id} を推奨します。ミリ秒だけのキーは再試行で即座に重複排除が壊れます。
生のシークレットをログに出さない。 ハッシュまたはプレフィックス付き識別子のみを保存し、ログベンダーを第二の爆発半径にしないでください。
以下は本番でよく見る帯域の目安です。SLAに合わせて調整し、ベンダー保証と混同しないでください。
スケジューラとノートPCを自前で回すのは、スリープ、不安定な自宅回線、OSアップグレードがcronとWebhookを半成功状態にするまでです。Gatewayと入口をVpsMeshの常時稼働Mac Miniクラウドノード上に置くと、外向きIP、メンテナンスウィンドウ、ハード分離が安定し、非IM自動化を趣味スクリプトからオンコール向けのループへ近づけられます。
入口を絞り、べき等にし、観測可能にすれば可能です。まずインストールとドクターのチェックリストでGatewayを安定させ、その後Webhookを開きます。
重複と送信元の証明不足です。共有シークレットまたはHMAC、エッジのIP制限、べき等ヒット時の同一意味の応答を追加してください。安定した外向きが必要なら料金ページでノードを比較できます。
メンテナンスをcronのピークとずらし、時刻を律儀に保ち、リージョン横断のコールバックタイムアウトを広げます。リモートMacの案内はヘルプセンターを参照してください。