エッジイングレス · 冪等性 · CI ペイロード · 3 層ゲートウェイログ · 非 IM トリガーガイドとのペア
小さなチームが運営していますOpenClaw ゲートウェイ24時間年中無休VPS / ドッカー仕事を進めることが多いインバウンドWebhookまたはCI 完了コールバック。 2 つの障害モードが支配的です。重複配送は副作用を増幅させる、 そしてログでは、障害がエッジ、ゲートウェイ、またはダウンストリーム ツールのいずれにあるのかが曖昧になります。。このガイドでは、認証およびタイミングウィンドウのマトリックス、6 ステップのロールアウト ランブック、コピー＆ペーストカールプローブ、そして3 段階のゲートウェイ ロギング分割トリアージ用に。トリガーソースアーキテクチャの場合は、次と組み合わせます。非 IM トリガーの自動化;チャネルとモデルの優先順位については、を参照してください。ランタイムのトラブルシューティング; TLS とリバースプロキシのデフォルトを調整する実稼働ドメインのリバース プロキシ チェックリスト。
IM チャネルはプラットフォームの再試行と目に見えるコンテキストを送信するため、メッセージの重複は簡単に推測できます。通常、Webhook と CI コールバックは、無人の窓;重複や順序どおりに到着しない場合は、モデルが不安定であるように見えます。 CI の再実行、キューのマージ、または手動ジョブの再試行では、1 つの論理ビルドに対して複数の端末通知が発行されることがよくあります。ゲートウェイが無視した場合pipeline_run_id、stage、 そしてconclusion冪等キーでは、一晩で二重支出、重複チケット、または重複したダウンストリーム マージが発生します。
クロックとタイムアウトのスタックは微妙です。コンテナのドリフトとホストの NTP によって、署名されたタイムスタンプ ウィンドウが壊れる可能性があります。エッジproxy_read_timeoutゲートウェイ 502 のような CI 再試行バックオフ サーフェスよりも短く、エッジが実際に接続を切断します。ログを分割せずにエッジ / ゲートウェイ / ツール、間違ったレイヤーを調整します。
重複した盲点:冪等性ヒットのない HTTP 200 のみをログに記録すると、財務や顧客から苦情が出るまで二重の副作用が隠蔽されます。
エッジとゲートウェイのギャップ:アクセス ログにはリクエスト ID がないため、ゲートウェイ トレースに参加できず、トリアージは推測に頼ることになります。
ペイロード ドリフト:CI テンプレートは JSON フィールドの名前を変更しますが、ゲートウェイは依然として古いキーに基づいてルーティングしており、不安定な分岐のように見えます。
IP ホワイトリストと動的出力:ホストされたランナー IP は、OpenClaw 認証バグとして誤って読み取られる 403 にローテーションします。
メンテナンスのずれ：発表されたダウンタイムと夜間の CI バッチにより、ゲートウェイのキューがいっぱいになる再試行の嵐が発生します。
脅威モデルに基づいて認証を選択します: 共有シークレットと内部 CI の IP ホワイトリスト。露出が増加する場合は、HMAC または mTLS - アプリ コード全体に分散せず、エッジまたはサイドカーで検証します。
| オプション | 運用コスト | Typical threat | こんな方に最適 |
|---|---|---|---|
| 共有キー + ヘッダー | 低い | 鍵漏洩後の偽造コストが低い | イントラネット CI、単一チーム、迅速なキーローテーション |
| HMAC (ペイロード ダイジェスト) | 中くらい | 実装エラーは誤った拒否やバイパスにつながる可能性があります | 耐タンパー性とシンプルなリプレイウィンドウを必要とする Webhook |
| 無記名トークン (短期) | 中くらい | トークン漏洩ウィンドウはTTLと流通チェーンに依存します | すでに OIDC/発行サービスを導入しているチーム |
| mTLS | 高い | 証明書のローテーションと失効のチェーンは複雑です | マルチテナント、強力なコンプライアンス、長期固定統合ソリューション |
TLS 終端とリバース プロキシ配線は運用チェックリストに従っており、ゲートウェイはローカルにバインドされていると想定します。 Webhook をオンにする前に混合コンテンツや WebSocket のドロップを修正するか、ログにノイズが多いままになります。
URL とパスを凍結する: Webhook と CI コールバックに別のパス プレフィックスを使用し、同じ場所とコントロール UI の静的リソースを混在させることを禁止します。
リクエスト ID の挿入: X-Request-Id のエッジ生成または透過的な送信、ゲートウェイ ログは、3 セグメントの相関関係を容易にするために同じフィールドを出力する必要があります。
冪等キーを定義します。delivery_id または CI の check_suite_id + job_id +結論を組み合わせ、重複排除ストレージに書き込み、TTL を設定します。
アライメント時間ウィンドウ: 署名またはタイムスタンプ検証ウィンドウは、最大 CI 再試行間隔および予約 NTP ドリフト マージンより大きくする必要があります。
フォールト挿入セルフテスト: 重複したペイロードと順序が崩れた結論を意図的に送信して、副作用の数が常に 1 であるかどうかを検証します。
アーカイブ監査フィールド: 呼び出し元 IP、キーのバージョン番号、冪等のキー ヒット結果を記録します。保存期間は 200 件のみを保存するのではなく、内部コンプライアンスを満たしています。
curl -sS -X POST "https://YOUR_DOMAIN/openclaw/hooks/ci" \
-H "Content-Type: application/json" \
-H "X-Webhook-Signature: sha256=REPLACE" \
-H "X-Idempotency-Key: pipeline-12345-success" \
-H "X-Request-Id: probe-$(date +%s)" \
--data '{"event":"workflow_job","conclusion":"success","repository":"acme/app"}'
ヒント: プローブはテスト ウェアハウスでのみトリガーしてください。運用環境では、IM チャネル キーとの混合を避けるために、キーに独立した回転ウィンドウを設定する必要があります。
階層 1 — エッジ:ゲートウェイに接続する前に、アップストリームのステータス、バイト数、および request_time のリバース プロキシ アクセス ログを読み取ります。ここでの 499/502 は、モデル ルーティングではなく、タイムアウトまたは TLS/SNI の問題を意味します。
階層 2 — ゲートウェイ:認証失敗、べき等ヒット、キューの深さ、および JSON 解析エラーを追跡します。と比較するランタイムのトラブルシューティングリクエストがハンドラーに到達しなかったかどうかを確認します。
階層 3 — ツール/モデル:CI が HTTP 200 を認識した場合や、空の応答エラーを見逃した場合でも、ツール呼び出し ID とアウトバウンド HTTP ステータスを組み合わせます。
注: 完全なキーまたは署名の原材料を情報レベルのログに入力しないでください。監査では、代わりにキーのバージョン番号と切り捨てられたフィンガープリントを使用できます。
ワンクリック関連付け: カスタマー サービス チケットについては、まず X-Request-Id を尋ね、3 つのログをそれぞれ 1 回検索して、結論を書き込みます。
階層化アラーム: Edge 5xx と Gateway 4xx は同じ沈黙ルールを共有してはなりません。そうしないと、再試行ストームについて誰も知ることができなくなります。
テンプレートの確認: 「障害レベル、最初の例外フィールド、冪等キー、呼び出し元 IP バージョン」の 4 つの列を再利用できるように記録します。
内部レビューのデフォルト - 外部に何かを約束する前に、CI コールバック SLA に置き換えます。
| チームの成熟段階 | Webhook エントリー戦略 | 最優先の改善 |
|---|---|---|
| 0→1検証 | 共有キー + 手動カール | 冪等なキーとリクエスト ID を補完し、手動キー配布の作成を禁止します。 |
| 1→10コラボ | HMAC + IP/CIDR 許可リスト | CI と外部サプライヤー間で 2 セットのキーと監査バケットを分割する |
| 10→100スケール | 有効期間の短いトークンまたは mTLS + レート制限 | ゲートウェイの監視を統合アラームとオンコール レイヤ化に統合 |
一時的な VPS エグレスと手動キーにより、移行中に Webhook フレークが増幅されます。 1 つの運用ストーリーで OpenClaw、CI コールバック、実稼働グレードの Mac キャパシティを必要とするチームは、通常、次のようなメリットを得ることができます。VpsMesh クラウド Mac Mini レンタル: 予測可能なリージョンとネットワーキングのため、Webhook トリアージとビルド トリアージは同じ語彙を共有します。
最初のチェックリバースプロキシアクセスログアップストリームのステータスと遅延を確認し、同じ内容でゲートウェイ ログを検索します。X-Request-Id、次にツール呼び出しを詳しく調べます。安定した出力ノードを注文する場合は、注文ページ。
を終了します設置と医師のチェックリストWebhook を有効にする前に。それ以外の場合、同じ署名エラーが 3 つのログ層すべてに表示されます。