GitHub Webhook を OpenClaw 系 ゲートウェイ（リモート Mac）へつなぐ典型失敗は三つです。公網 URL の取り違え、署名対象と読み取る生ボディの不一致、重い処理による配信タイムアウト。TLS 入口の外向き再現、X-Hub-Signature-256 と NTP、401／timeout の切り分けを手順化します。launchd 安定性手順書 と 自己ホスト Runner FAQ を併読してください。
1. 秘密の前に、公網コールバックを文字どおり固定する
GitHub はインターネット側からのみ呼びます。nginx／LB／Cloudflare Tunnel／ngrok でも ホスト名・パス・ヘッダ改変 を記録し、LAN 内ではなく 外向き curl -v https://… で再現してください。ループバック成功はヘアピン NAT や誤 SNI を隠します。プロキシがボディを再バッファすると署名対象とズレます。正規 URL を一つに決め、GitHub へ同じ文字列だけ貼ります。
curl がゲートウェイの想定する早期 ACK 経路以外を返すなら、署名以前に入口を直す。2. 署名と時刻の方針
GitHub は 生 POST ボディ に HMAC-SHA256 をかけ X-Hub-Signature-256（sha256=）で送ります。TLS 後の同一バイト列を定時間比較し、プレフィックス誤りは即拒否。Bearer 等と併用するなら Mac は NTP で秒を合わせます。配信 ID をべき等キーにし、再送で副作用が増えないようにします。
3. リポジトリ設定の合わせ込み
基本は application/json、SSL 検証は有効のままチェーンを直す。Recent Deliveries の本文がプロキシ議論の決め手。シークレットは両端を同じ窓でローテし、片側だけ更新すると 401 が続きます。
4. 401 が出るのに秘密は合っているとき
層別に見ます。Webhook パスへ掛かる Authorization ミドルウェア、Basic／CDN 制限の誤スコープ、JSON 再シリアライズ後の署名比較、二重ルートでエッジが先に 401。配信 ID をゲートウェイログと同一ミリ秒で突き合わせます。
5. タイムアウトとコールドスタート
配信側は速い応答を期待します。重処理をインラインに抱えると Mac は動いても GitHub は timeout。キューへ逃がし、可能なら早く 202 を返し、プロキシの read／write も現実値へ。launchd で import をウォームし、再送前提のべき等を維持します。
6. 貼り付けチェックリスト
- 外向き
curlの URL が GitHub と末尾スラッシュまで一致。 - HMAC は生ボディ。プロキシの変換・伸長なし。
- Mac 時刻は NTP で数秒以内。
- Webhook パスにグローバル認証を掛けない。
- 速応答＋遅延処理＋再送耐性。
常駐ゲートウェイに Mac mini を置く理由
Webhook は時計とディスクと軽負荷の揺れに敏感です。Mac mini（Apple Silicon）は単スレ性能と 低アイドル電力 のバランスが良く、TLS と署名検証を常時載せても説明しやすい。Unix／Homebrew／macOS の Gatekeeper／SIP／FileVault で露出自動化の説明責任も取りやすいです。
摩擦最小の起点は Mac mini M4。リージョン分散の専有ノードは Macstripe ホームページでレイテンシを照合してください。
