Оглавление: префлайт · риски · матрица · фрагменты JSON · шаги · чек-лист · FAQ
Материал для команд, которые запускают Agno на арендованном удалённом Mac и хотят одинаковые гарантии для сервиса и для соседних репозиториев. Ниже — воспроизводимый контур: префлайт узла, loopback-шлюз, политика инструментов, разведение бюджетов времени, полуоткрытый circuit breaker и единый JSON-конверт отказа. Смежные паттерны: Strands Agents за OpenClaw, PydanticAI и JSON Schema на границе; для health-проб и IDE-моста используйте гайд по префлайту и пробам как часть обходного листа перед нагрузкой. Публичные страницы без входа: тарифы, покупка и аренда, документация.
Префлайт до первого вызова инструмента
Зафиксируйте версию OpenClaw и профиль железа одной строкой в журнале релиза. Выполните openclaw doctor --json и сохраните артефакт в каталог logs/preflight/: зелёный отчёт не заменяет проверку свободного места на томе логов и лимита открытых файлов, но даёт сравнимый снимок между ноутбуком разработчика и удалённым узлом. Согласуйте часовой пояс и NTP, иначе корреляция request_id между шлюзом и агентом в разборе инцидента будет дороже самого инцидента. Для сетевого контура SSH добавьте в чек-лист idle-timeout прокси и MTU VPN — те же параметры, что вы уже сводите в материале про health-пробы.
Три типовых провала
- Неявный каталог инструментов: модель предлагает имя вне политики, и побочный эффект успевает начаться до отказа клиента.
- Один таймаут на всё: ожидание первого токена, дорогой HTTP вызова инструмента и сериализация ответа смешаны — в логах невозможно ответить, на какой стадии оборвался запрос.
- Сырой текст в ошибке: в вызывающий код утекает completion или пользовательский ввод, а ретраи без идемпотентности удваивают запись во внешние системы.
Матрица где резать отказы
| Слой | Инвариант | Цена пропуска |
|---|---|---|
| Agno | Типизированные обёртки и локальные лимиты параллелизма | Защита только своего процесса |
| OpenClaw | Белый список имён и жёсткие лимиты времени на маршруте | Побочные эффекты и порча данных вниз по цепочке |
| Надёжность | Breaker, джиттер ретраев, идемпотентность записей | Своп на Apple Silicon и зависание воркеров |
Фрагменты JSON политики и ответа
Ниже — примеры без секретов: подставьте свои имена инструментов и версию политики. Токен шлюза храните в файле с правами 0600 или в Keychain, не копируйте в репозиторий.
Белый список загрузите как отдельный артефакт и пронесите ту же tools_policy_version в логи Agno и шлюза.
{
"tools_policy_version": "2026-04-30",
"allowed_tools": [
{ "name": "read_repo_file", "side_effect": "read", "max_payload_bytes": 65536 },
{ "name": "http_get_allowlisted", "side_effect": "network", "hosts_allowlist": ["api.example.internal"] }
]
}Границы времени на шлюзе держите выше клиентского HTTP-таймаута Agno на несколько секунд запаса, чтобы клиент получил структурированный отказ, а не обрыв сокета.
{
"gateway_timeouts": {
"first_token_soft_ms": 45000,
"full_completion_hard_ms": 120000,
"single_tool_execution_ms": 20000
},
"circuit_breaker": {
"window_sec": 60,
"open_on_consecutive_5xx": 5,
"open_on_schema_reject_streak": 4,
"half_open_probe_interval_ms": 8000
}
}Failure summary возвращайте как единственное тело ответа при отказе валидации, таймауте инструмента или открытом breaker; те же поля пишите в JSONL.
{
"outcome": "failed",
"request_id": "req_01JZ...",
"stage": "tool_execute",
"code": "TOOL_TIMEOUT",
"hint": "retry_idempotent_after_sec=30"
}Воспроизводимые шаги
1) Каталог и пользователь. Создайте сервисного пользователя, корень ~/agno-edge с подкаталогами config logs policies, репозиторий смонтируйте только для чтения, запись ограничьте scratch с квотой.
2) OpenClaw на loopback. Поднимите шлюз на 127.0.0.1, задайте порт в systemd LaunchAgent или аналоге, выполните openclaw doctor --json и приложите вывод к тикету релиза.
3) Политика инструментов. Загрузите JSON allowlist в шлюз, включите отказ до исполнения для имён вне списка, зафиксируйте tools_policy_version в переменных окружения Agno.
4) Agno и base URL. Направьте HTTP-клиент на http://127.0.0.1:<порт>/v1 через переменные окружения совместимого с OpenAI API профиля; запретите в CI прямой обход шлюза grep-ом по базовому URL.
5) Таймауты. Разведите бюджет первого токена, полного ответа и блока исполнения инструмента; в логах раздельно пишите latency_model_ms и latency_tool_ms.
6) Circuit breaker. Накопите в скользящем окне подряд идущие SCHEMA_REJECT и 5xx маршрута, после порога переведите маршрут в полуоткрытое состояние с джиттером бэкоффа и ограничьте число ретраев на уровне агента.
7) Failure summary. На любой ошибке шлюза формируйте компактный JSON с request_id stage code hint без сырого completion и без пользовательского ввода; пробросьте тот же объект в ответ API и в структурированный лог Agno.
Чек-лист перед нагрузкой
- Версия политики инструментов в git совпадает с переменной на шлюзе и в Agno.
- Клиентский HTTP таймаут строго ниже жёсткого лимита шлюза, отдельный лимит на исполнение инструмента задокументирован в runbook.
- Breaker: пороги окна и полуоткрытия зафиксированы, идемпотентность для инструментов с записью проверена сценарием повторной доставки.
- Тестовый запрос находится по
request_idв логах шлюза и агента, поля сводки не содержат секретов. - Soak не менее двух часов на удалённом Mac без интерактивной нагрузки на том же пуле unified memory.
Краткие ответы
Нужен ли дубль белого списка в Agno? Желателен как защита от ошибки разработчика, но юридически достаточным остаётся шлюз: он единственный видит всех клиентов.
Как жить с markdown-оболочкой вокруг JSON? Шлюз обязан вычищать фенсы до валидации иначе получите стабильные ложные SCHEMA_REJECT.
Где крутить пробы ближе к продакшену? На выделенном узле из раздела покупки и аренды с тем же профилем памяти.
Публичные страницы без логина: главная, блог, помощь, тарифы, покупка.
Итог: белый список на шлюзе, разведённые таймауты, полуоткрытый breaker и единый failure summary дают воспроизводимый контур Agno за OpenClaw на удалённом Mac без утечки секретов в ответах об ошибках.