Модели оптимистичны; инфраструктура — нет. Если разрешить агенту вызывать shell, HTTP или инструменты над репозиторием без схематических ограничений и жёстких таймаутов, один плохой цикл может исчерпать воркеры, забить диск или устроить штурм внешнего API. Решение скучное и повторяемое: проверять аргументы до исполнения, «плавить» длинные вызовы, открывать цепь (circuit breaker) после предсказуемых отказов и переиспользовать один шаблон повторов там, где есть побочные эффекты.

Статья предполагает, что OpenClaw уже установлен на удалённом Mac и что вы поднимаете loopback-шлюз для IDE или безголовых агентов. Ориентацию по платформе смотрите на главной; пути установки, токены и основы шлюза — в центре помощи · раздел OpenClaw. Если нужен выделенный узел Mac mini M4 под долгоживущий шлюз и песочницы инструментов, сравните регионы на странице покупки (просмотр без входа в аккаунт). Тот же расклад каталогов естественно сочетается с гайдом IDE-мост, минимальные права и health-пробы: сохраняйте разделение «репозиторий только для чтения / scratch для записи», чтобы логи валидации и трассы повторов не засоряли дерево исходников.

Шлюз и каталог навыков (skills)

Воспроизводимость начинается с путей, которые команда может скопировать один в один. На удалённом Mac держите состояние шлюза под одним корнем вроде ~/.openclaw (конфигурация, токены, указатели локального кэша), а версионируемые навыки — в ~/openclaw-skills/<имя-навыка>/ с манифестом skill.yaml или skill.json и при необходимости подкаталогами schemas/ и scripts/. Зарезервируйте ~/openclaw-scratch/ для структурных логов, временных полезных нагрузок и вывода проб — не корень Git-рабочей области.

  • Один манифест на навык. Объявляйте имена инструментов, точки входа, политики по умолчанию и ссылки на файлы JSON Schema, чтобы поведение ревьюилось в Git.
  • Секреты отдельно. Храните токены в файлах 0600 и подключайте через OPENCLAW_TOKEN_FILE; манифесты должны указывать только путь, без встроенных секретов.
  • launchd или менеджер процессов. Запускайте шлюз с KeepAlive, ротацией логов в ~/openclaw-scratch/logs/gateway.log и переменными окружения на каталоги навыков и scratch — plist задокументируйте рядом с манифестами.

После изменения раскладки выполните openclaw doctor --json > ~/openclaw-scratch/probe/doctor-last.json, чтобы зафиксировать базовую линию до тонкой настройки инструментов.

Пример проверки JSON Schema

Подключайте inputSchema к каждому инструменту, который модель может вызвать. Предпочтительны JSON Schema Draft 2020-12 или Draft-07 — в точности та версия, с которой собран валидатор вашей сборки OpenClaw. Проверка должна выполняться до запуска subprocess или HTTP-клиента; при ошибке возвращайте машиночитаемое сообщение с именем поля, ожидаемым типом и нарушенным ограничением — тогда модель сможет исправить вызов.

Пример: инструмент «получить задачу», которому нельзя подсовывать произвольные URL и неограниченные метки:

{ "name": "linear.fetch_issue", "description": "Получить одну задачу Linear по стабильному id", "inputSchema": { "type": "object", "additionalProperties": false, "required": ["issueId"], "properties": { "issueId": { "type": "string", "pattern": "^[A-Z]{2,10}-[0-9]+$", "maxLength": 32 }, "includeComments": { "type": "boolean", "default": false } } } }

Правила, которые экономят недели отладки: для объектов задавайте additionalProperties: false, ограничивайте строки maxLength, массивы — maxItems, режимы перечисляйте через enum вместо свободного текста. Громоздкие схемы выносите в ~/openclaw-skills/linear/schemas/issue.fetch.json и ссылайтесь из манифеста. При провале валидации логируйте tool, correlationId и путь ошибки валидатора — не логируйте сырые пользовательские секреты из отклонённых полезных нагрузок.

Таймауты и параметры предохранителя (circuit breaker)

Таймауты — это предохранители: они не дают одному инструменту «заморозить» пул воркеров. Circuit breaker останавливает серии плохих вызовов, чтобы не долбить зависимость. Выражайте оба в манифесте навыка (или в общем policies.yaml), чтобы у инструментов были наследуемые значения по умолчанию и точечные переопределения.

  • executionTimeoutMs — предел wall-clock после успешной валидации. Для HTTP-обвязок начните с 8–30 с, для ограниченных обходов репозитория — 60–120 с, для чистых CPU-преобразований — заметно меньше.
  • queueWaitMs (опционально) — сколько вызов может ждать в очереди, прежде чем шлюз ответит, например, 503 tool_backpressure; защищает от стада параллельных вызовов от модели.
  • Окно circuit breaker — например breaker.failureThreshold: 5 подряд идущих сбоев или breaker.errorRatePercent: 40 за скользящее окно 60 с, затем breaker.openDurationMs: 30000 с быстрым отказом новых вызовов и кодом вроде breaker_open.
  • Half-open — разрешите одну пробную инвокацию после окна «открытой цепи», чтобы восстановление не требовало ручного перезапуска.

Числа фиксируйте в ревью рядом с каждым инструментом. Если SLO внизу по цепочке меняются, сначала обновляйте манифесты, потом перезапускайте шлюз — избегайте «тайных» переменных окружения, известных одному ноутбуку.

Повторы и экспоненциальная отсрочка (backoff)

Повторы должны жить в одном общем шаблоне, а не копипастой sleep внутри каждого скрипта. Для идемпотентных чтений используйте экспоненциальный backoff с джиттером; для записей — строго ограниченное число попыток и явные ключи идемпотентности там, где их поддерживает провайдер. Практичный старт для шлюза на удалённом Mac, вызывающего внешние API:

retry: maxAttempts: 4 initialDelayMs: 200 multiplier: 2.0 maxDelayMs: 8000 jitterRatio: 0.2 retryOnHttpStatus: [408, 425, 429, 500, 502, 503, 504] nonRetryOnHttpStatus: [401, 403, 404, 422]

Сочетайте повторы с ключами идемпотентности на мутирующих маршрутах. Для subprocess-инструментов по умолчанию не включайте автоповтор, пока манифест не помечает инструмент как idempotent: true, а скрипт не различает коды выхода «временная инфраструктура» и «плохой ввод». На каждую попытку пишите структурную строку: attempt, delayMs, errorClass, correlationId. Когда цепь открыта, повторы отключайте и отдавайте модели состояние breaker, чтобы она сменила стратегию, а не усилила ущерб.

FAQ: логи и устранение неполадок

Всплеск ошибок валидации после смены модели. Новые модели чаще добавляют лишние ключи или удлиняют строки. Ужесточайте схемы постепенно: сначала логируйте неизвестные ключи верхнего уровня, затем включайте additionalProperties: false, когда трафик «чистый».

Срабатывает таймаут, а сервис снаружи выглядит здоровым. Проверьте DNS и рукопожатие TLS с самого Mac, а не только с ноутбука. Сопоставьте executionTimeoutMs с p95 задержки; холодный старт соседей по serverless часто превышает оптимистичные дефолты.

Circuit breaker не закрывается после восстановления. Убедитесь, что включены half-open пробы, классификация ошибок не смешивает 4xx с 5xx, часы синхронизированы (скос ломает скользящие окна). Ищите «застрявший» тип вроде ECONNRESET, который не исчезает из логов.

Повторы усиливают лимиты запросов. Забыли обработку 429 или потолок backoff. Уважайте Retry-After, если заголовок есть, и снижайте maxAttempts для «шумных» инструментов.

В логах успех, а эффекта нет. Инструмент мог вернуться до завершения асинхронной работы. Либо удлините таймаут под весь пайплайн, либо разделите «поставить в очередь» и «опросить статус» на два инструмента со своими схемами.

openclaw doctor зелёный, а в рантайме инструменты падают. Doctor часто проверяет бинарники и конфиг, а не живые учётные данные. Запустите канареечный инструмент в dry-run, убедитесь, что пользователь шлюза читает файлы токенов, и что пути в окружении launchd совпадают с интерактивной оболочкой.

Кратко: нормализуйте каталоги шлюза, навыков и scratch; валидируйте каждый инструмент по JSON Schema до исполнения; задайте таймауты и окна circuit breaker; централизуйте экспоненциальный backoff с джиттером; протаскивайте correlation ID через валидацию, попытки и переходы breaker. Такой стек превращает «хаос агента» в операции, которые можно репетировать на удалённом Mac и передать следующему инженеру без устной истории.

Если такой подход совпадает с тем, как вы хотите запускать агентов в 2026 году, вынесите шлюз на железо под вашим контролем: изучите облачные варианты Mac mini M4 на странице покупки, сверьтесь с тарифами на странице цен и держите ранбуки в центре помощи. Когда будете готовы к выдаче машины, откройте консоль с главной и разверните одни и те же политики «схема впереди, таймаут и повторы по шаблону» везде, где крутится OpenClaw.