OpenClaw: колбэки и облачные Mac runner — низкое доверие, изоляция, идемпотентность и аудит

Ключевые тезисы

Сначала криптография, потом тяжёлый парсинг: HMAC в постоянном времени (или mTLS), окно допустимого сдвига часов и защита от повторов лучше, чем «сначала доверять форме JSON».
Изоляция по умолчанию: обработчик webhook только валидирует и кладёт непрозрачную единицу работы в очередь; runner забирает задачи по приватному каналу, чтобы отравленный payload не запускал shell напрямую из полей запроса.
Идемпотентность — это контракт данных: стабильный event_id, хранилище дедупликации и ограниченные повторы с джиттером; дубликаты доставки — отдельная метрика, а не сюрпиз только в логах.
Поля аудита намеренно скучные: кто инициировал, на какой аренде runner, с каким дайджестом артефакта — одинаковые столбцы в HTTP-логах, сообщениях очереди и stdout CI.

Абстрактное фото с серверной стойкой и подсветкой, символизирующее автоматизацию и сетевые границы — Автоматизация по webhook должна исходить из модели враждебных повторов и частичных сбоев; обложка иллюстративна.

1. Низкое доверие к входящим: не заставляйте runner быть файрволом

Считайте каждый POST недоверенными байтами, пока криптографическая проверка не завершится успешно. Подпись считайте по сырому телу (до произвольных JSON-трансформаций), отклоняйте отсутствующие метки времени и держите короткое серверное скользящее окно для сдвига Date или заголовка вроде X-OpenClaw-Timestamp. Для плохой подписи возвращайте 401, для битого конверта — 400, чтобы оповещения чисто разделялись по причинам. Если TLS терминируется на edge-прокси, зафиксируйте в runbook, где именно стоит верификатор, иначе «ускорение» обходом проверки станет нормой.

Ограничивайте частоту и по IP источника, и по идентификатору ключа подписи: украденный ключ не должен заливать весь пул. В лог пишите только усечённые отпечатки секретов и полезной нагрузки, не сырые токены. Та же дисциплина, что и на границе подписи артефактов в CI, должна действовать на HTTP-границе; см. также Apple Silicon, облачный Mac: iOS/macOS CI — codesign, нотаризация, stapler и границы связки ключей: воспроизводимый конвейер и таблица типичных отказов — там хорошо видно, как идентичность артефакта проходит по конвейеру.

2. Изоляция выполнения: шлюз → очередь → runner

Обработчик webhook делает минимум работы: проверка, нормализация во внутреннюю схему, запись в долговечную очередь, ответ 202 с корреляционным идентификатором. Тяжёлые шаги — git fetch, установка зависимостей, xcodebuild — выполняются на краткосрочной аренде runner с политиком исходящего трафика только к разрешённым реестрам. HTTP-воркер не должен порождать shell-команды из полей webhook.

Когда runner сидит за туннелем или при split DNS, заранее проверьте MTU и маршруты: иначе «webhook принят» расходится с «задача реально выполнилась». Практический разбор сетевых краёв — в WireGuard и сопряжение со шлюзом при трансграничном удалённом доступе: устранение неполадок MTU, асимметричной маршрутизации, разделения DNS и наблюдение за задержками (регион и конфигурация облачного Mac). Для контейнеризованных вспомогательных сервисов рядом с runner полезно заранее согласовать лимиты CPU/SSD с тем же языком, что и в материалах про производственный Docker на облачном Mac в этом блоге.

3. Идемпотентность и повторы: at-least-once без хаоса

Заложите модель как минимум однократной доставки. Требуйте event_id (или хеш канонического payload) и храните исходы в таблице дедупликации с TTL, согласованным с горизонтом повторов. Клиентские повторы — экспоненциальная задержка с джиттером; сервер при дубликате должен отвечать тем же HTTP-образом, что и при первом успехе, чтобы upstream-реконсиляторы оставались простыми.

Задайте максимальное число приёмов на сообщение очереди и поток dead-letter с приложенным исходным конвертом: постмортему нужны подписанные метаданные, а не только внутренний JSON. Счётчик duplicate_suppressed держите отдельно от validation_failed, чтобы плейбуки дежурных оставались короткими.

4. Наблюдаемость и поля аудита: шпаргалка для runbook

Протяните одни и те же идентификаторы через access-лог HTTP, записи очереди и stdout runner. Минимально полезный набор столбцов:

Поле	Где живёт	Зачем аудиторам и SRE
`trace_id` / `correlation_id`	Edge, приложение, очередь, runner	Сквозная реконструкция без джойна только по временным меткам
`event_id` + `delivery_attempt`	Конверт webhook, DLQ	Доказательство подавления дубликатов и политики повторов
`signing_key_id`	Верификатор, аудит-лог	Ротация ключей и радиус компрометации
`runner_lease_id` / класс хоста	Планировщик, метаданные CI	Связь автоматизации с физической или виртуальной ёмкостью
`git_ref` / дайджест артефакта	Запись сборки	Воспроизводимость для security review
`policy_version`	Снимок конфигурации шлюза (хеш)	Объясняет, почему вчера приняли, а сегодня отклонили

Структурированный JSON-лог бьёт прозу: одна строка на переход состояния (received, enqueued, leased, succeeded, failed_terminal). Персональные данные не выводите из полей webhook; сопоставляйте актёров с непрозрачными ID в IdP.

Метрики, которые не врут при повторах

На поверхности webhook держите сигналы в духе RED: скорость запросов, доля ошибок с разбиением 4xx против 5xx, задержка на границе постановки в очередь (не полное время сборки). Возраст самого старого сообщения в очереди отделяйте от занятости runner: так видно «вход здоров, не хватает ёмкости» против «верификация жрёт CPU». Глубину DLQ и число подавленных дубликатов выводите как отдельные gauge; алертить лучше на устойчивый рост, а не на одиночные всплески — после аварий бурсты повторов нормальны.

5. Заключение

Цепочки webhook ломаются скучно: сдвиг часов, двойная доставка и runner, который поднялся без того же DNS, что у шлюза. Зафиксируйте в дизайне верификацию, обработчики «только постановка в очередь», идемпотентность и общие корреляционные ID раньше, чем оптимизируете минуты сборки — тогда автоматизация OpenClaw остаётся читаемой и для security review, и для вас в три часа ночи.