ゲートウェイと Webhook 設定
対象チャンネルで統合（Incoming Webhook）を有効にし、発行される https://<サーバ>/hooks/<id> 形式の URL を一度だけ取得します。ゲートウェイは Content-Type: application/json で {"text": "..."} もしくは attachments を送ります。自前 Mattermost の場合はサーバの TLS 終端と証明書チェーンを確認し、外向き通信はゲートウェイから Mattermost の FQDN（必要なら :443 以外の公開ポート）へ限定します。フォワードプロキシを挟む場合は ゲートウェイのレート・セッション FAQ と同様に、デーモンと同じ HTTPS_PROXY で curl し CONNECT が通ることを先に検証してください。
- 手順 1. ゲートウェイ上にルート（例：
/hooks/mattermost/build-status）を用意し、キューから来たイベントを JSON に整形してから Mattermost へ転送する。 - 手順 2. 手元で
curl -X POST -H 'Content-Type: application/json' -d '{"text":"probe"}' '<Webhook URL>'を実行し、チャンネルに 1 行出るまで繰り返す（URL はシェル履歴に残さない）。 - 手順 3. クラスタ切替時も出口はゲートウェイのみ更新する（フェイルオーバー）。
多ノード状態の集約（最小手順）
各ビルド Mac は CI の生 JSON をそのまま Mattermost に送らず、ゲートウェイ内の共通キーに正規化してから 1 本の text または attachments を組み立てます。プロジェクト別設定 が分かれていても、通知用キーは揃えておくとフィルタや検索が楽です。
| 正規化キー | 例 | Mattermost 表示のコツ |
|---|---|---|
workflow | GitHub Actions の workflow 名など | 1 行目のラベルに使う |
state | success / failure / cancelled | 絵文字や色付き attachments で区別 |
branch・commit | 短縮 SHA とリポジトリ URL | クリックでログへ飛ばす |
mesh_node_id | Runner 名・ホストラベル | フッタに「どの Mac か」を明示 |
provider_run_id | run_id / pipeline id | state と組み合わせて冪等キーにする |
429 や一時的な 5xx は キュー再試行 と同様に指数バックオフし、400 はペイロード修正まで再試行しない方が安全です。
トークンと最小権限
Incoming Webhook の URL にはパス上の秘密トークンが含まれます。Git にコミットせず、例として /etc/openclaw/secrets.d/mattermost/build-status.url を 0440 でゲートウェイ実行ユーザのみが読めるようにします。シークレット最小権限 の方針に沿い、ビルドワーカーにはファイル自体を配りません。漏えいや退職時は統合を再発行しファイルを差し替え、古い URL は即無効化します（手順の型は IM トークンローテ と同じです）。サーバ側で「投稿ユーザ名・アイコン」の上書きを許可する場合のみ username / icon_url を使い、不要なら省いて攻撃面を狭めます。
メッセージが届かないときの FAQ
| 現象 | 切り分け |
|---|---|
| CI は緑だがチャンネルが無音 | ゲートウェイの送信ログの HTTP ステータス、text が空でないか、Webhook が無効化されていないか |
curl は成功するが CI からは失敗 | ゲートウェイまでイベントが届いているか、キュー詰まり、認証ヘッダの誤り |
| 特定ノードだけ欠落 | その Mac が古い URL で直接 POST していないか、プロキシ迂回の残り |
| HTTP 200 だが表示がおかしい | Mattermost の Markdown 制限、attachments の fallback、モバイルでの折りたたみ |
| 急に 404 | Webhook 再発行後にゲートウェイの秘密ファイルが未更新 |
まとめ・次の一手（ログイン不要）
ゲートウェイ一箇所に Webhook URL を集約し、出站は Mattermost サーバへだけ、mesh_node_id と provider_run_id で観測と冪等を揃えるのが 2026 年の最小セットです。関連記事は OpenClaw 特集 と ブログ一覧 からどうぞ。