2026年 OpenClaw Webhook／Hooks のリモート物理 Mac ゲートウェイ設定：トークン認証・リバースプロキシ経路・CI 連携の再現可能 Runbook（401／404 切り分け＋FAQ）
GitHub・チャットブリッジ・社内バスから OpenClaw を叩くプラットフォーム担当は、CI は緑でも本番 Webhook だけ 401／404 で沈黙する経験をしがちです。本稿は 2026 年向けのコピペ運用として、Bearer と転送ヘッダの整合、nginx／Caddy のパス接頭辞と OpenClaw 登録経路の一致、GitHub Actions がエッジと同じ契約を再生するまでを一本化し、症状対照表・検証 7 ステップ・引用用閾値・FAQ をまとめます。
1. リモート Mac ゲートウェイで Webhook が静かに失敗する理由
物理 Mac は Unix ソケットと launchd のライフサイクルが読みやすく、地域に近い CI からの遅延も小さいため Webhook の受け皿として優秀です。しかし障害モードはしばしば「OpenClaw ダウン」ではなく契約のズレです。SaaS が呼ぶ URL・プロキシが書き換えるパス・検証側が読むヘッダの trio が独立してドリフトします。
- ヘッダ欠落： リバースプロキシは、明示的に転送しない限り
AuthorizationやカスタムX-*を落とします。CI 側は認証済みに見えても、上流はトークンを一度も見ていません。 - 二重接頭辞： エッジで
/agents/openclawに載せたのに、ハンドラは接頭辞なしの/hooks/...のみ登録—エッジ無しの localhost curl では消える 404 の典型です。 - シークレット分裂： GitHub Secrets だけ更新し Mac 側検証子を忘れる（またはその逆）と、どの Runner シャードが走るかに相関した間欠 401 が出ます。launchd／ゲートウェイ常駐のログと突き合わせて、ローテーションの片側漏れを疑ってください。
2. トークン／パス設計マトリクスと 401／404 対照
設計レビューと、プロキシまたは OpenClaw の更新のたびに下表を再走査してください。「脆弱」列の項目にはオーナーとロールバック用チケット雛形を紐づけます。
| 観点 | 脆弱パターン | 本番目標 |
|---|---|---|
| トークン運搬 | アクセスログに残る ?token= |
Authorization: Bearer または HMAC 署名ヘッダを端到端で転送 |
| パス対応 | strip／rewrite 規則のない location / 丸投げ |
公開パス → プロキシ規則 → OpenClaw ルート表の三点セットを文書化 |
| TLS エッジ | 「VPN があるから」平文 Webhook | Caddy／nginx で TLS 終端。社内バスにはオプションで mTLS |
| CI トリガ | 担当者端末だけの curl |
本番と同じ JSON 封筒をバージョン管理された workflow が POST |
| 可観測性 | OpenClaw ログのみでプロキシ access log なし | request_id をエッジとアプリで 60 秒以上突き合わせ可能に保持 |
2.1 HTTP 401／404 の第一切り分け（オンデマンド）
| 応答 | 第一疑い | 即時確認 |
|---|---|---|
| 401 | Authorization 欠落／別 vhost の認証／トークン片側のみ更新 | エッジ access log でヘッダ有無（ハッシュ化）、Mac 直 curl と公開 URL でヘッダ集合を diff |
| 404 | パス接頭辞の取り違え、strip_prefix 過剰、IPv6 で別 server ブロック | TLS 終端で $request_uri を記録し、成功した手元 curl とバイト一致で比較 |
GitHub Actions から同じ契約を安定して流す設計は、2026年 グローバルチーム：GitHub Actions 自前 macOS Runner で Set up job の長尾遅延を近接物理 Mac がどう圧縮するか（Actions キャッシュ・ミラー・Runner リージョン配置の閾値マトリクス／FAQ） の Runner／キャッシュ配置とも相性が良いです。OpenClaw と CI の相性の整理は OpenClawはCIでの実行に適していますか？物理Macが安定している理由 を参照してください。
3. 再現可能な Runbook（7 ステップ）
管理者 SSH のあるリモート Mac で実施し、パスとヘッダはミリ単位で記録してください。インシデントの勝敗はここで決まります。
- 契約の凍結： メソッド、完全な公開 URL、JSON スキーマ、必須ヘッダ（大文字小文字含む）を wiki と workflow コメント先頭に同一ブロックで貼る。
- 上流のローカル証明： Mac 上で
curl -fsS -H "Authorization: Bearer $TOKEN" -X POST http://127.0.0.1:<port>/<文書化パス>を最小ボディで実行。DNS 前に HTTP 2xx。 - プロキシ整合： nginx／Caddy で TLS を終端し、公開パスを OpenClaw が登録した上流パスへマップ。
strip_prefix／rewrite使用時は成功・失敗各 1 回について$request_uriと上流 URI をログに残す。 - 認証ヘッダの明示転送：
Authorizationとベンダ署名ヘッダを必ず通す。「安全デフォルト」で省略されるのが不可解 401 の主因です。 - GitHub Actions 配線：
workflow_dispatchとリリースタグで動くジョブを追加し、Secrets のOPENCLAW_WEBHOOK_URLとOPENCLAW_WEBHOOK_TOKENで POST。ステータスが 2xx 以外ならジョブ失敗。ペイロード形は本番と同一にする。 - 401／404 ドリル： 誤トークン 1 回（401 期待）と余分なパス 1 回（404 期待）を送り、プロキシとアプリ双方のアラート条件に載るか確認する。
- ロールバック束： プロキシユニット、証明書パス、旧 location を変更前にスナップショット。四半期ごとに 15 分以内復旧をリハーサルする。
4. 引用用の閾値
- 合成 Webhook SLO： Mac が対話負荷で空いている前提で、CI から端到端 POST の p95 が 2.5 秒以内で 2xx。5 分で連続 3 回失敗ならページ。
- ローテーション窓： トークン更新後は 30 分の単一変更窓で検証子と CI Secrets を揃え、チケットクローズ前に合成ジョブを再生する。
- ログ相関： エッジとアプリケーションの要求 ID を最低 7 日保持し、週末リリースでもディスク丸ごとスナップショット無しで追えるようにする。
- IPv6 規律： DNS が AAAA を出すなら、IPv6 対応 Runner からの試験か、Actions 側で IPv4 明示を検討。ファミリ混在 vhost は「手元 curl だけ通る」404 の温床です。
5. FAQ
Mac 上の curl では成功するのに、公開 URL では HTTP 401 になるのはなぜ？
localhost curl には Bearer が付いていても、LB 経路で Authorization が落ちたり、別 vhost が別認証を要求していることがあります。プロキシ access log でヘッダ存在（ハッシュ化）を確認し、OpenClaw の検証子が期待するヘッダ名と一致するかを突き合わせてください。
手動 curl は成功するのに GitHub Actions だけ 404 になるのはなぜ？
パスと DNS ファミリの不一致が典型です。Actions が /api/hooks/openclaw を叩きエッジが /hooks/openclaw だけ、あるいは IPv6 がデフォルト server に当たる、など。TLS 終端で $request_uri を記録し、成功した curl とバイト単位で比較してください。
Webhook トークンは GitHub Secrets のみでよい？ Mac 側は？
送信側は CI の Secrets、検証側は Keychain・launchd 環境変数・root 所有 0600 ファイルなどに分離し、リポジトリには置きません。両者を同一メンテナンス窓でローテーションしてください。
macOS や OpenClaw を上げたあと、どのくらいの頻度で合成 Webhook を流すべき？
ゲートウェイ・プロキシ・OS の更新の 30 分以内に、CI プローブと公開 URL 経由の手動 curl の両方で 2xx を確認します。フック登録表や動的 import はマイナー semver でも変わり得るため、アップグレードはスキーマ移行と同列に扱います。
6. この自動化エッジに Mac mini／macOS が合う理由
Webhook と hook ワーカーは、POSIX なソケットセマンティクス、launchd による予測可能な常駐、Runbook どおりに動く TLS ツールチェーンを求めます。macOS なら WSL やコンテナブリッジの驚きなく、Homebrew・curl・Caddy／nginx がスクリプトの前提どおり振る舞います。
Apple Silicon の Mac mini は待機電力がおおよそ 4 W 級でファンレスに近い静音性があり、夜間も CI からの POST を受け続けるゲートウェイに向きます。Gatekeeper・SIP・FileVault は TLS ファーストの Webhook 設計とも両立し、デスクトップ OS の緩さと引き換えに自動化速度を落とす必要がありません。
ネストした VM より実機でエッジから上流まで同じスタックを再現したい場合、Mac mini M4 はコストと消費電力のバランスが取れた出発点です。本稿で検証した手順をそのまま本番ノードへ載せ替えるなら、ZoneMac のノード案内から専用 Apple Silicon 環境を検討してください。
専用 Mac mini で Webhook／Hooks を受ける
OpenClaw ゲートウェイ、署名ビルド、CI 隣接フック向けの物理 macOS ノード—本 Runbook が前提とする launchd と TLS スタックをそのまま使えます。