6 モジュール · 表 · 8 手順 · チケット 4 行 · 受け入れ表
すでに OpenClaw を自前の Mac もしくはレンタル Mac に載せている担当者に向け、CRM・社内工番・採用 ATS 等からの Webhook/HTTP コールバックを Gateway 経由で同じ可観測線上に載せる手順をまとめます。ポイントは curl 127.0.0.1 が通った「その場の成功」では足りず、ループバック、リバースプロキシ、外部事業者の再送文脈を一枚の図に落とし、同一 request id をアプリ・Nginx・相手受領ログに貫くことです。併読として v2026.4.12 マルチチャネル、Gateway 逆プロキシ＋HTTPS、無応答切り分け、SSH ローカルポートフォワーディングを置き、HTTP 専用の「薄い導管」とそれ以外を混同しない土台づくりにします。本文は6 セクション（相関 id の運用原則を含む）、モード比較表、戻る先が明示された 8 手順、チケット用の短文 4 行、15 分 VNC 表、FAQ です。レンタル先が VNCMac の場合、同じ macOS ユーザーに SSH 編集と VNC 下のブラウザ証明をまとめやすいのが大きい利点です。ここに書いていない 相手 SaaS ごとの HMAC 仕様は、必ず自社の契約文とポータル画面で確定し、日付・鍵のローテ幅・ 429/5xx の扱いを一行で README に残すこと。そうしないと、来月の小さな互換性変更に静かに飲まれるのはいつも Webhook 側からです。ステージングと本番で 負荷の形をそろえられないなら、少なくとも 再送回数の上限と到着間隔は本番想定の合成テストに含め、そこで初めて openclaw 側のキュー挙動を見積ります。逆に、PoC ばかりで台帳がないと、誰のどのトークンが公網面を開けているのかの説明に週末を溶かします。ここを守るのが、本稿の「最小」と「地味ながら効く冪等」の境界です。チームに Windows 主戦が混ざる場合、Mac まわりの ショートカット脳内モデル（ループバック=プロセスのユーザー）と、Linux 鯖の docker 上の 127.0.0.1 幻想のズレに注意。OpenClaw の doctor 出力のユーザー名を、実際に VNC ログインした顔と毎週照合するだけでも事故は減ります。HTTP 系はさらに ブラウザの信頼ストアが絡むため、「bastion からの curl=全世界の真理」という誤学習に早めに歯止めをかけてください。
第 1 類は 環境指紡の喪失 です。127 で返る本文が、公網 443 では 502/504 になるのは「モデル遅延」以前に proxy_read_timeout や Upkeep/KeepAlive の不整合 のことが多い。レンタル Mac 上では、まず openclaw --version ・ openclaw doctor ・ 公開 FQDN の SAN 満了日を、同じ change のテキストに固定します。第 2 類は 冪等の欠如 です。事業者が 5xx 後に 同じ事業 id を再投します。会話 id を毎回新規採番していると、監査不能・課金二重化・サポート地獄が揃います。第 3 類は ログ断絶 です。Nginx にはリセット理由が残り、Node 側には到達前に落ちた痕跡がない、という絵を一つの request id で接続しなければ、責任分界が週次で衝突します。第 4 類は GUI しか出ない層 です。クライアント証明・鍵束・SNI/OCSP まわりは、Gateway と同じユーザーで開いた Safari/Chromeの一次情報に値します。第 5 類は チャット連携 をここに混ぜる誤作動です。IM の多チャネル文を読めば、長寿命接続と 即時 HMAC 配送の SLO は同じ Nginx でも別物と整理できます。第 6 類は 半分だけ SSH トンネル、半分だけ 443 公開 の図。社内系は ループバック導の長文 を一ページ化し、誰の 127.0.0.1 かを毎週点呼してください。
ここに加え、社内審査で後から刺さる地雷 として、ペイロード中の PII のマスク方針、再送ログの保持日数、障害当日に「生本文」を共有してよい相手、をテンプレ化しておきます。技術的な最小連携の外側で燃えるのは、往々にしてこの手の 法務/セキュ職能が読める一文の欠如 です。Webhook は便利ですが、契約上「どこに止めるか」を書かない限り、エンジニアの tail -f には全部が来てしまいます。そこに気づく前に、本番用とデバッグ用の二段サンプル JSONを用意し、本番用ではマスク必須フィールドを明記しておくと、オンテコール中の人的ミスを減らせます。加えて、相手事業者の メンテ告知ページの RSS かメーリングに最低一人が乗る運用にすると、夜間の「急に 401 だけ帰る」系が「鍵日付かも」と早まります。逆に、社内承認待ちの間に staging の HMAC 秘密を全員のノートPCに焼いているような状態は、早期にローテ手順付きで切り戻し、SecretRef/権限分離の方針（OpenClaw 他稿参照）に寄せるのが得策です。こうした週明けの人間的負債を減らす努力も、一見地味ながら Webhook 運用の 真の TCOを左右します。なお、Windows 同席メンバー向けのハンドシェイク資料には、「Mac の GUI=そのユーザーの 127.0.0.1」の一文を太字にして置くのが有効で、PowerShell から WSL2 越しに叩いた 200 と、実際の prod 到達点がズレる事故を減らせます。
バージョン針： openclaw・doctor・パートナー API 版を一括でタグ化。
署名針： 意図的に誤秘密→正秘密を staging で。
時刻針： NTP と署名許容偏位を一行で定義。
引継針： request id + 画面キャプ + Nginx 行、三点セットで Confluence/Notion に。
到達保証/遅延/再投コスト/運用責務で選ぶ。数字は自社台帳に置換。
| 形態 | 向く場面 | 危険 | Gateway 側 |
|---|---|---|---|
| 受動 Webhook | 事後イベント、署名、HTTPS 外向き可 | 再送、レート、時計ズレ | 行ログに request id、4xx/5xx の意味分離 |
| 定期 Pull | 出のみ NW、cron 親和 | 鮮度、枠、ページング | openclaw cron --tools 白明文化 |
| WebSocket 等 | 双方向低遅延 | 再接続、wss 終端、プロキシアイドル | 逆プロキシ稿の Upgrade 整合 |
事業者文書に 「同 id を再投する」 とあれば、冪等は最優先のゲート。IM 導線（マルチチャネル）を混在パスにしないこと。
中盤で迷ったら 手順 1の指紡からやり直す。中継 SSH と短時間 VNCの役割分離を崩さない。
指紡： 版、doctor 抜粋、公開名の証明書、listen 一覧をテキスト化。
ループバック唯一： 本番ユーザのブラウザで控制台。静かなら 無応答手順 併用。
最小 POST： grep 一発行に残る小 JSON。
逆プロキシ： HTTPS 入門稿の Host/WS/Timeout を点検。公網 FQDN を 実ブラウザで。
署名： 誤/正、ログで判別可。
冪等： 同一事業 id 二重投下→会話一つに収束の証拠残し。
チャンネル混線なし： IM 用 URL へ流し込まない。再確認 多チャ。
引き継ぎ三種： マスク済 curl スニペ、コメント入り location、3 層揃いの request id 例。
P1: 127 と 443 の業務意味が同型 P2: 同 id 再投は状態分岐を増やさない P3: request id が 3 ログで一致 P4: 主因は 証明書/中継/ハンドラ/LLM のどれか一つ
無応答の「画面で確かめる」文化を、外向き HTTPS の検査にも適用。短時間・低解像度で回す。
| 観点 | 操作 | 合否 |
|---|---|---|
| 二系統の控制台 | 127 と公網、Network タブの混合コンテンツ | curl 意味と同型 |
| 時刻 | メニューバー＝ログ UTC 乖離 | 署名窓内 |
| クライアント証明 | 手続中ダイアログ | 夜間無人に残置なし |
| ユーザー一貫 | Activity、doctor 表示名 | 衝突なし |
本番以降の差分は、コードより 誰のダッシュに何が立つか。429 は相手/自前 admission/下流 LLM の三つに分解し、同じ座標系で見せる。混線回避に 多チャ文のバック圧知見を借り、Webhook 再送嵐の前に 入口レートを宣言する。半ばトンネル半ば 443 では、SSH 本稿の判断表に沿って、毎週 ループバック図を更新。Mac 自前よりレンタル＋固定手順＋VNC 証拠で回すチームの方が、週明け再現性のコストは下がりやすい。障害中は 入口停止→並列上限制御→再試行方針の順。プロンプト同時五本は最後。ここに 月次の振り返りで「図面が一ページ化されているか」のチェックボックスを足すと、属人化した「あの日はたまたま同じ人が全部見ていた」状態にブレーキをかけられます。大企業子会社では、情シス発行のクライアント証明の有効期間が短く、更新のたびに再ダウンロードが必要という地味な運用制約に Webhook 終端が飲まれる例も多い。カレンダー予約と、openssl s_client ベースの二段階受け入れ、をセットで入れておくと、更新前夜の焦りを減らせます。
最後に、学生チーム向け注意として、学内 Wi‑Fi のキャプティブ/隔離で外向き 443 試験が不安定、という層向けの一言を添えると親切。大学 VPN を挟む二段抜きで「ローカルでは成功した」図を作らず、レンタル先の帯域 SLOを明記。VNCMac の SSH と VNC のセットを買い切り、夜間作業の 短い GUI 作業帯をカレンダー化しておくのが、HTTP 導通と将来の on-call 両方の投資回収率を上げます。
| 症候 | 先に | 後で |
|---|---|---|
| 公 5xx / 私 2xx | 中継・keepalive | アプリ層最適化 |
| 署名エラー多発 | 時計・秘密・本文 | 下流 |
| 重複作業＝重複金額 | 冪等/DB 一意 | UI |