Шесть модулей · таблица · 8 шагов · 4 фразы · VNC
Когда OpenClaw уже крутится на Mac, следующий шаг — втащить в тот же контур внешние системы по HTTP: входящий вебхук с CRM, биллинга, внутреннего helpdesk. Успешный curl 127.0.0.1:18789 ещё не готовая схема: после обратного прокси и публичного HTTPS появляются другие тайм-ауты, TLS, Host, SNI, ретраи и риск двойной доставки одного и того же event_id — без идемпотентности вы получите всплески расхода и «лишние» диалоги, которые потом невозможно согласовать с аудитом.
Материал ниже дополняет уже существующие длинные гайды: многоканальность (IM) — с другой семантикой SLO и другими лимитами; публичный шлюз и Nginx — куда должен вести путь вебхука; «нет ответа» — порядок triage, когда виноват не «промпт»; проброс портов по SSH — как сознательно соединить loopback на удалённом Mac с вашей сетью. Мы сфокусируемся на транспорте и контракте HTTP: что логируется, как подписывается тело, как одна цепочка request id проходит через шлюз, бизнес-обработчик и, при необходимости, логи поставщика вебхука.
На удалённом Mac VNCMac полезно держать один и тот же пользователь macOS и для запущенного Gateway, и для короткой сессии VNC, где в браузере открывают цепь сертификатов, системные часы и модальные окна доверия. SSH удобен для скриптов и curl, но нельзя вечно обходить графическую плоскость, если SLO требуют «зелёной» цепочки к публичному имени. В статье: модуль про типичные ловушки, таблица сравнения вебхука, pull и WebSocket, восемь шагов от localhost к продакшену, четыре готовых формулировки для тикета, 15-минутная проверка в VNC, блок про корреляцию и ответственность — без этого интеграция останется демо, а не эксплуатацией с квартальным отчётом по 429 и согласованным PII.
Локальный 200 OK не доказывает, что после публичного имени и ретраев поставщика сценарий тот же. Ниже — шесть классов проблем, с которыми чаще всего сталкиваются при первом внешнем HTTP, и что положить в тикет заранее, чтобы смена не сидела до ночи с неразличимыми 502 в трёх логах сразу.
Потеря «отпечатка среды» — в тикет не попали версия openclaw, конфиг, хостнейм, notAfter сертификата и реальный listen. Без снимка невозможно воспроизвести «как вчера», когда Nginx вчера ещё не крутился.
Нет идемпотентного ключа — поставщик вебхука при 5xx или внутри своей сети повторит тот же event_id. Ваша сторона должна отвечать «дубликат принят» или отбрасывать повтор до создания нового диалога с моделью.
Разорванная наблюдаемость — в заявку попали только строки приложения, а error-лог Nginx и ответ апстрима не сопоставлены по времени. Один x-request-id (или близкий аналог) должен быть виден хотя бы в трёх слоях.
Крипто- и сетевой слой только в GUI — mTLS, срок клиентского сертификата, цепь доверия в брелоке, SNI, иногда корректные часы для токенов. Это не то, чем исчерпывается ssh и curl в сыром виде: нужна короткая сессия VNC под тем же пользователем, что и Gateway.
Путаница с IM-каналами — путь чата (Telegram, Slack) и путь внешнего вебхука в одном access-логе без меток. Разнести location и SLO, см. многоканальный гайд.
«Полу-туннель» + публичный 443 — часть трафика уходит в ssh -L, часть в реальный публичный Nginx, а в документации нарисован один путь. Исправьте гайд по пробросу: где намеренно loopback, где публичное имя.
Практическое добавление: пишите в runbook одно предложение про PII (что резать в логах) и где хранить секрет подписи вебхука. Ротацию ключей не обсуждайте в публичном мессенджере — сразу vault + календарь и окно VNC для кликов, если вендору нужен новый отпечаток в брелоке.
| Режим | Когда | Риск | Gateway |
|---|---|---|---|
| Входящий вебхук | события, HMAC, HTTPS | ретраи, rate, часы | id в логе, 4xx чёткие |
| Pull | только исход | устаревание, квоты | cron+allowlist |
| WebSocket | низкая задержка | idle, wss | wss+Upgrade |
Если поставщик вебхука гарантирует повтор при 5xx или тайм-ауте, идемпотентность — не «доработка», а условие релиза: дубль по тому же бизнес-ключу не должен создавать второй агентский сценарий. Каналы мгновенных сообщений (IM) и внешний HTTP по разному ведут себя при 429 и перегрузке: на одной машине их можно хостить рядом, но не сливайте SLO, тайм-ауты и дашборды в одну кучу — иначе квартальная смета по токенам снова превратится в дискуссию «у кого виноват лимит».
Режим pull (исходящие запросы с вашей стороны) удобен, если вендор не может открыть исходящий HTTPS с своей стороны: тогда в runbook зафиксируйте какой Unix-пользователь крутит cron, какой токен, и не пересекается ли это с интерактивной сессией — иначе вы отладите «у себя в терминале», а ночной джоб падает в другом $HOME. Для WebSocket (wss) важны правильные заголовки Upgrade и тот же шаблон, что в чеклисте по прокси; не вешайте крупные синхронные POST на тот же location без настройки буферов — снаружи это похоже на «медленную модель», хотя узкое место в обратном прокси. После миграции БД проверьте уникальный индекс на event_id тестовым дублем: иначе повторы вебхука внезапно начнут падать с нарушением уникальности, а не с «логичным» 200. Наконец, отслеживайте глубину очереди у поставщика, а не только 5xx — длинная очередь часто предшествует видимым обрывам. Таблицу выше пересматривайте при каждом существенном релизе поставщика, а не раз в год.
Порядок намеренно жёсткий: сначала фиксируем, что крутится и под кем, затем сеть и подписи, и только в конце — смысловые ветки в агенте. Застряли на середине — возвращайтесь к шагу 1 и снимите «снимок» ещё раз, не крутите промпт, пока транспорт нестабилен. Дежурной схеме нужна одна картинка «loopback / публичный хост / апстрим»; без неё в чате разрастается три часа несовместимых догадок.
Отпечаток — openclaw --version, openclaw doctor, фактический listen, FQDN публичного URL, notAfter по сертификату, пользователь, под которым живёт Gateway. Сохраните один блок текста в тикет — не перескакивайте в прод без него.
127.0.0.1 и браузер того же пользователя, что и процесс Gateway. Если консоль «молчит» или визуально пуста при живом systemctl/launchd, сначала пройдите триаж «нет ответа» — оно про heartbeat и неправильного пользователя, а не «про модель».
Минимальный POST в хендлер: телефонное поле, фиктивный внешний id, текстовый ответ, который легко grep’ать в трёх логах. Не гоняйте сразу 2 МБ JSON «как в проде» — сначала докажите, что транспорт съедает контракт.
Обратный прокси и TLS по чеклисту: server_name, проксирование заголовков, тайм-ауты, WebSocket, если планируется wss. В VNC откройте публичный FQDN в Safari/Chrome — убедитесь, что цепочка такая же, что у внешнего вендора (без внутреннего CA, который он не знает).
Подпись (HMAC, Bearer и т.д.): на staging ошибитесь намеренно один раз, второй — верно, убедитесь, что логи различают 401/403/200 и не везде «тихо 200» с пустой телом.
Идемпотентный повтор — в одном временном окне дважды шлёте тот же id сделки/тикета. Второй ответ: либо «уже обработано» с тем же следом в логе, либо явно описанная ветвь без нового треда в агенте.
IM-URL не путайте с URL вебхука. Если на одной машине и мессенджер, и внешний JSON, пусть в Nginx два location с разными префиксами и, при необходимости, разным limit_req. Подробнее — многоканальность.
Передача смене — один архив: пример curl (заголовок с подписью, но без секрета в чистом виде), фрагмент location Nginx, скрин цепи сертификата, строка трёхлоговой корреляции с request_id. Следующему дежурному не должно требоваться пять чатов, чтобы воссоздать путь пакета.
P1: loopback=пуб. смысл P2: дубль id не плодит ветвь P3: id в 3 логах P4: виноват один слой: TLS, прокси, хендлер, модель
Формулировки ниже намеренно сухие: их можно вставить в Jira/YouTrack без пересказа «часа в Zoom». Они не заменяют полные логи, но фиксируют где сломалось и что уже исключено.
duplicate / тот же correlation_id; в логах нет второго создания сессии агента. Ключ идемпотентности: K = … (описание поля, не значение секрета).»Окно стоит планировать коротким и осознанным: не «сидеть в VNC весь день», а пройти чеклист, который нельзя закрыть с чисто текстовой консоли. За 15 минут обычно укладываются: публичное имя в браузере, сравнение с curl -v, сверка часов, клик по ожидаемой модалке брелока.
| Проверка | Что сделать в GUI | Критерий «готово» |
|---|---|---|
| 127 и 443 | DevTools → Network на публичном URL; сравнить с curl -v с bastion | Одинаковая семантика ответа, нет скрытого смешанного контента и лишних редиректов, которых нет у поставщика |
| Время | Меню часов, таймзона, сопоставить с логом в UTC | Окна подписи HMAC/токенов не «плавают» на часы; нет сюрпризов при сравнении с логом вендора |
| Сертификаты / mTLS | Клик по цепочке, при необходимости — импорт клиентского в брелок | Нет «зависшей» модалки; ночной cron не умрёт в ожидании клика |
| Пользователь и джобы | Activity Monitor / ps + графическое согласование с doctor | Gateway, тестовый curl и фоновые крон-задачи согласованы с одной учётной записью и $HOME |
429 (Too Many Requests) может прийти с трёх разных плоскостей: поставщик вебхука (ограничил вход), публичный шлюз / Nginx (ваши limit_req), модель или платформа LLM внутри OpenClaw. На дашборде для инцидента обязательно пишите какой слой, иначе финансы и SRE снова спорят в одной таблице. Культура раздельных лимитов и для IM, и для HTTP — в многоканальном гайде как эталон «чтобы чаты и автоматизация не делили одну цифру».
В разгар инцидента: сначала остановите лавинообразный вход (квоты, падение, отключение тестовых поставщиков), снимите глубину очереди и один рычаг — не пять сразу. После стабилизации приложите к разбору: diff изменений Nginx/прокси, скрин цепочки из браузера, три строки логов с общим x-request-id (или аналогом). Для внешнего аудита — только замаскированные сэмплы тела вебхука и хэш ключа, не сырой секрет. Два офиса в разных часовых поясах должны опираться на одну wiki-страницу с одной схемой: иначе к следующему релизу снова появятся две несовместимые картины «как оно на самом деле работает».
Аренда облачного Mac на VNCMac сочетает удобный вход к покупке и сравнение тарифов: важна не «маркетинговая цифра», а возможность в одном пользователе держать Gateway, браузер и при необходимости короткую сессию VNC для согласования с безопасностью — без скачка между личной машиной и продом.
IM и HTTP врозь.
Читать →wss, TLS, порты.
Читать →Порядок triage.
Читать →Плохая идея, если внешняя сторона жёстко ретраит. У чата и синхронного JSON разные SLO: для вебхука часто нужен ответ быстрее, чем длинный вызов модели; разведите proxy_read_timeout, политику ретраев поставщика и внутренний тайм-аут на вызов LLM. Иначе вы будете гасить 504 в Nginx и «тихо» 429 у модели одновременно.
Практично, чтобы подписи не пересекались: сотрудник не сможет случайно тестовым HMAC дёрнуть прод. Staging-URL пусть никогда не публикует те же X-* токены, что прод, даже при «таком же бинарнике OpenClaw». Ротация ключа: календарь, два активных ключа в переходный период, потом снятие старого — с шагом в VNC, если клиентскому сертификату нужен клик в брелоке.
curl с bastion доказывает, что маршрут и TLS с внешней сети похожи на клиента, но не заменяет проверку в браузере на том же Mac, где крутится UI и брелок. Для mTLS, иногда SNI, иногда локальных доверительных окон macOS, нужен короткий GUI-сеанс. См. также статью о пробросе: важно, чтобы схема loopback была осознанно согласована с Nginx, а не «как-то заработало с ноутбука дежурного».
Минимальный «боевой» срез — не столько один успешный curl, сколько один сквозной идентификатор в трёх логах и доказуемая схема, как повтор того же id не плодит второй разговор с агентом. Когда в команде мешают Windows, Linux и облачный Mac, одна wiki-страница с одной диаграммой «кто, куда и под каким пользователем» снижает количество несовместимых толкований «что у нас в проде».
Арендный облачный Mac (SSH для скриптов, VNC для цепи доверия) хорошо ложится на сценарий, где Gateway, браузер и редкие системные клики должны соседствовать под одним пользователем — ближе к SRE, чем «я с ноутбука в VPN». Перед вводом публичного вебхука ещё раз согласуйте с InfoSec политику логов (PII, сроки хранения) — иначе постморте начнется раньше, чем вы снимите метрику по x-request-id. Внутренние API до внешнего поставщика часто ссылают через проброс портов — убедитесь, что эта ветвь не путает loopback в проде с тем же FQDN, куда стучится CRM.