Оглавление: матрица входов · развёртывание · алиасы и router · бюджет и breaker · сводка ошибок · типовые сбои · FAQ
Если вы уже строили цепочку «агент → шлюз → инструменты», перенесите ту же дисциплину на LLM-трафик: внешний мир видит только шлюз с Bearer из Dashboard, а LiteLLM держит карту провайдеров и политику переключения моделей. Паттерн повторов и health на стороне шлюза разобран в материале про LangGraph, токен шлюза и объединённые алерты; песочница, минимальные права на каталоги и пробы — в гайде IDE-мост, diff и health на удалённом Mac. Чтобы сводки стыковались с трассами и токенами в дашбордах, опирайтесь на матрицу наблюдаемости GenAI на Mac.
Три узких места до первого инцидента
Прямой доступ к LiteLLM с рабочих станций. Любой ноутбук с ключом провайдера становится точкой утечки; при увольнении вы ротируете всё, а не один токен среды.
Одна модель в конфиге без алиасов. Команды начинают хардкодить реальные идентификаторы в репозитории, и переключение маршрута превращается в массовый рефакторинг вместо правки model_list.
Отсутствие бюджета на ошибки и саммари. Провайдер мигает пятисотыми, клиенты бесконечно ретраят, счёт растёт, а в алерте нет ни имени логической модели, ни correlation id — ночной дежурный гадает по обрывкам логов.
Матрица: кто принимает внешний трафик
| Схема | Плюсы | Минусы и риск |
|---|---|---|
| Только LiteLLM наружу | Быстрый старт, встроенный router | Нет единого слоя навыков OpenClaw; сложнее сузить scope токена до конкретного сценария |
| OpenClaw gateway → LiteLLM на 127.0.0.1 | Один публичный контур, минимальные ключи на узле, навыки и аудит на шлюзе | Нужно явно согласовать таймауты стрима и пути OpenAI-совместимого API |
| Прямые вызовы провайдера из каждого сервиса | Нет промежуточного процесса | Размножение секретов, разные лимиты ретраев, несовместимые логи |
Развёртывание и конфигурация: пошагово
1) Каталог и пользователь. На удалённом Mac заведите корень ~/llm-edge с подпапками config, logs, tmp. Запускайте LiteLLM и OpenClaw от одного непривилегированного пользователя или разведите UID, но сохраните общий групповой доступ только там, где это необходимо. Файлы с ключами провайдеров — 0600, не коммитьте их в git.
2) Виртуальное окружение и порт proxy. Создайте venv, установите пакет LiteLLM, зафиксируйте версию в lock-файле. Поднимите процесс на 127.0.0.1 и свободном порту, пропишите команду в plist launchd с ThrottleInterval для авто-рестартов без busy-loop.
3) Gateway как фронт. Настройте навык или маршрут шлюза на базовый URL http://127.0.0.1:<PROXY_PORT>/v1. Клиенты передают только логические имена моделей и заголовок Authorization к шлюзу; LiteLLM не публикуйте на LAN. При необходимости добавьте локальный firewall rule, блокирующий вход на порт proxy с любых адресов кроме loopback.
4) Токен из Dashboard. Выпустите отдельные токены для разработки, нагрузочных тестов и продакшена с разными scope и TTL. Запретите владельцам ноутбуков хранить ключи провайдера — пусть на конечных машинах живёт только доступ к шлюзу или вовсе SSH-сессия без секретов.
5) Health и зависимости. Объедините проверку /health шлюза с лёгким models или chat/completions запросом к LiteLLM через тот же внутренний путь, чтобы зелёный PID не маскировал отсутствие маршрута к провайдеру.
6) Приёмка. Прогоните три сценария: корректный вызов логической модели, искусственный отказ одного маршрута с переключением на резерв, истечение токена шлюза. Зафиксируйте ожидаемые HTTP-коды и текст алерта.
Алиасы моделей и мультимаршрутизация
В model_list задайте короткие имена для команд вроде fast, reason, embed и сопоставьте их реальным идентификаторам провайдера. Включите router или явный fallback-порядок: сначала дешёвый маршрут, затем «тяжёлый» при ошибках определённого класса. Ограничьте RPM и TPM на каждую запись, чтобы один эксперимент не съедал квоту всей организации. Документируйте политику в runbook рядом с таблицей стоимости и SLO по задержке.
Бюджет отказов и circuit breaker
Опишите окно наблюдения и порог доли ошибок или серии подряд неудачных запросов, после которых маршрут помечается как недоступный и трафик уходит на резервную модель либо возвращается контролируемая ошибка на шлюз без бесконечных ретраев. Согласуйте max_retries в LiteLLM с политикой повторов на OpenClaw, иначе вы умножите нагрузку на API провайдера и получите ложные срабатывания breaker. Клиентские коды 401, 403, 422 не считайте поводом для автоматического переключения маршрута.
Сводка ошибок обратно в шлюз или вебхук
Включите обработчик успеха и ошибки в LiteLLM или отдельный навык OpenClaw, который получает структурированный JSON: логическое имя модели, код статуса, длительность, усечённый request_id, признак стрима, без тела промпта и без полного completion. Прокиньте тот же идентификатор в access-лог шлюза, чтобы дежурный за минуту связал инцидент с конкретным вызовом. Для долгосрочного анализа экспортируйте поля в коллектор метрик или трасс согласно матрице наблюдаемости выше.
# Пример минимальной пробы цепочки (подставьте порт и токен шлюза)
curl -sf -H "Authorization: Bearer $OC_TOKEN" -H "Content-Type: application/json" \
-d '{"model":"fast","messages":[{"role":"user","content":"ping"}],"max_tokens":8}' \
http://127.0.0.1:${OC_GATEWAY_PORT}/v1/chat/completionsТиповые сбои при настройке
502 от шлюза при живом LiteLLM. Сверьте путь /v1, таймаут стрима и заголовок Host; часто виноват неверный префикс маршрута в конфигурации навыка.
Модель не найдена. Проверьте опечатку в алиасе и факт перезапуска процесса после правки YAML.
Breaker «дребезжит». Расширьте окно метрик, исключите отмены со стороны клиента из счётчика ошибок, уменьшите параллелизм нагрузочного скрипта.
FAQ
Нужен ли публичный HTTPS на самом LiteLLM? Нет, если весь внешний трафик завершается на шлюзе с корректным TLS; LiteLLM остаётся на loopback.
Как хранить ключи нескольких провайдеров? Разнесите по файлам окружения с правами только для пользователя сервиса; в git кладите лишь шаблон без значений.
Можно ли комбинировать локальную модель и облако? Да, через несколько записей model_list и правила router; важно явно маркировать чувствительные запросы маршрутом без отправки данных наружу.
Где безопаснее крутить proxy — ноутбук или арендованный Mac? На выделенном узле в дата-центре стабильнее питание, сеть и ночные джобы; ноутбук оставьте тонким клиентом с SSH.
Кратко: шлюз даёт минимальные права и единый аудит, LiteLLM — мультимаршрутизацию и алиасы, бюджет ошибок защищает квоту, а короткая сводка сбоев с correlation id ускоряет разбор инцидентов без утечки промптов.
Чтобы повторить весь стек на изолированном узле Apple Silicon, откройте страницу покупки удалённого Mac — она доступна без входа в аккаунт, как и публичные тарифы; после выбора региона зафиксируйте порты и секреты в центре помощи и перенесите plist с узла в репозиторий инфраструктуры без ключей.