2026 OpenClaw: пользовательские провайдеры web_search, openclaw.json, исходящая безопасность и многоуровневый ранбук doctor

Когда пользовательский провайдер web_search — зрелое решение

Встроенные поисковые интеграции в дистрибутивах агента оптимизируют время до первого «hello world». Редко в них заложены история размещения данных, лимиты по счёту или требование, чтобы каждый исходящий IP агента был внесён в allowlist параноидальной ИБ-службы. Переход на собственный провайдер означает осознанный выбор HTTP-контракта, аутентификации из хранилища секретов, которым владеет команда, и наблюдаемости, которую финансы могут сверить с актом.

В регулируемых контурах часто действует внутренний сервис извлечения, где ACL на документы уже применены. Указание tools.web.search на такой сервис переиспользует политику вместо того, чтобы строить параллельный «теневой» индекс. Плата — инженерия: схемы ответов должны оставаться стабильными, SLO публикуются явно, частичные отключения обрабатываются без тихого отката в публичный интернет, если политика это запрещает.

Команды, чувствительные к стоимости, натыкаются на HTTP 429 у вендора задолго до исчерпания токенов модели: ретраи и «переобучение» инструментов раздувают число запросов. Пользовательская маршрутизация позволяет шардировать ключи, вводить бюджеты по командам или душить автоматизации, которые дергают поиск на каждом вызове инструмента. Эти бюджеты документируйте рядом с CPU и RAM — по поведению они ближе к скрытому вычислительному ресурсу, чем к «мелкой строке в облаке».

Планирование доступности обязано учитывать корпоративные forward proxy и split-horizon DNS. Шлюз, который на ноутбуке резолвит vendor.example, на сервере за инспектирующим прокси с кастомными корнями может получить иной сертификат или иной путь доверия. Проверяйте с тем же POSIX-пользователем, теми же файлами окружения и тем же способом запуска, что и в проде; иначе «у меня работает» превращается в недоказуемый артефакт.

Операционная симметрия важна: если для флаков Telegram вы уже применяете цепочку status → шлюз → doctor → логи, используйте её и для поиска. Разные симптомы, одна дисциплина — меньше противоречивых вики-страниц в разгар инцидента.

Наконец, относитесь к правкам конфигурации как к коду: pull request, ревьюеры, понимающие SSRF, и проверка JSON-схемы в CI. Материал про прод-хардненинг и SSRF напоминает: исходящий HTTP заслуживает того же подозрения, что и входящие вебхуки, если строки от модели превращаются в URL.

Ранбуки фиксируют, кто утверждает смену URL провайдера, в каком окне допустим перезапуск шлюза и как откатиться по дисциплине снимков из заметок об обновлении MCP. Без владельцев поиск становится интеграцией, которой все пользуются и никто не сопровождает, пока не сгорят квоты.

Мультирегиональные развёртывания требуют явного ответа: все ли кластеры шлюзов бьют в один эндпоинт поиска или в региональные зеркала. Расхождение DNS даёт «флаппинг» сравнений: в Токио запрос проходит, в Дублине — нет при идентичном JSON, если не логировать фактический хост на запрос.

При смене модели или провайдера LLM в инциденте поток вызовов инструментов может всплеском перечитать каталог возможностей. Ограничьте параллельные вызовы обнаружения инструментов: иначе авария модели превращается в аварию поиска через случайное усиление.

Документируйте контракт ответа: максимальное число сниппетов, допустимые поля, запрет на редиректы на неожиданные схемы. Это снижает число споров между командами данных и платформы о том, «кто должен был отфильтровать URL».

Согласуйте политику логирования: какие заголовки и query-параметры маскируются до централизованного стека. Поисковые строки часто содержат контекст, который нельзя светить в SIEM без редактирования.

Включите в регламент периодический аудит переменных окружения, на которые ссылается блок auth: устаревшие имена после апгрейда CLI оставляют «тихий» отказ с понятным только по tcpdump симптомом.

Разложение боли по полочкам

Боль 1: расползание секретов. Ключи API, вшитые в JSON, который ещё и синхронизируется dotfile-менеджерами, утекают быстрее, чем долгоживущие SSH-ключи. Предпочитайте косвенные ссылки на окружение и короткоживущие токены там, где это позволяет IdP.

Боль 2: SSRF через параметры поиска. Если модель подставляет произвольные строки запроса, а бэкенд наивно ходит по первым попавшимся ссылкам, вы фактически собрали SSRF. Нужны серверные allowlist, нормализация схемы и запрет внутренних шаблонов имён хостов.

Боль 3: ложноотрицательные результаты doctor. Утилита проверяет локальную согласованность, а не здоровье удалённого вендора. Дополняйте её синтетическими канареечными запросами и внешними чёрными ящиками.

Боль 4: горячая перезагрузка против холодного рестарта. Как в заметках о жизненном цикле MCP, часть сборок частично подхватывает JSON до полного перезапуска процесса шлюза. При сомнении — чистый рестарт и контроль числа дочерних процессов.

Боль 5: путаница поиска со скрапингом. Массовое скачивание страниц оставьте за выделенным fetch с кэшем и уважением к robots; поиск не должен превращаться в неконтролируемого краулера.

К каждой боли привяжите метрику и владельца: иначе постмортем сводится к обмену ощущениями, а не к измеримым действиям на следующей неделе.

Количественные ограничители против сюрпризов в счёте

Считайте запросы в час по автоматизации, по ключу и по сценарию. Мягкие алерты на семидесяти процентах суточного лимита по договору, жёсткие остановки — сначала для некритичных агентов. Сопоставляйте графики объёма с числом ретраев модели: бэкофф циклы тихо умножают HTTP-вызовы.

Ведите p50 и p95 раздельно: хвост часто раскрывает DNS или рукопожатие TLS, которое «среднее» скрывает. Сверяйте часы на хостах шлюза, иначе корреляция с внешними инцидентами разъедется.

Фиксируйте размер полезной нагрузки, возвращаемой модели. Перегруженные сниппеты раздувают стоимость контекста downstream, даже если сам поиск кажется дешёвым. Усечение на прокси — разумный компромисс, если политика позволяет.

Ведите тетрадь инцидентов с точными curl-воспроизведениями и редактированными заголовками: дежурный не должен гадать, это регрессия OpenClaw, корпоративного прокси или внешнего API.

Ежеквартально сверяйте счета финансов с внутренними метриками: расхождения часто находят забытые ключи на стейджинговых шлюзах.

Задайте бюджет ошибок: допустимая доля 5xx в сутки, максимум последовательных отказов до пейджинга, медианное время восстановления после инцидента вендора. Постмортемы по поиску прикладывают логи шлюза, логи прокси и точный дифф JSON, предшествовавший событию.

Ночные автоматизации планируйте так, чтобы тяжёлые индексации не делили ключ с интерактивными пользователями. Раздельные ключи для людей и роботов упрощают атрибуцию и предотвращают блокировку критичных сценариев шумными ретраями.

На прокси задокументируйте максимальную длину сниппета и запрещённые MIME: дешевле отсечь сюрприз на периметре, чем платить токенами downstream.

Добавьте контроль одновременных поллингов при деградации вендора: иначе «проверка здоровья» превращается в дополнительную лавину к поисковому API.

Храните эталонные ответы канарейки (хэш тела или детерминированные поля) для регрессионных тестов после обновления бэкенда: смена ранжирования не должна маскировать поломку авторизации.

Исходящая безопасность и границы SSRF

Поиск — исходящий HTTP, но он участвует в той же модели доверия, что и входящие вебхуки. Если бэкенд разыменовывает URL из сниппетов, проверяйте схемы и хосты до любого последующего fetch. Мышление должно совпадать с руководством по SSRF, хотя направление трафика иное.

Allowlist на уровне OpenClaw необходим, но недостаточен: дублируйте на корпоративном egress, чтобы плохой конфиг не стал единственным барьером. Логируйте блокировки с идентификатором автоматизации, чтобы связать с паттерном промпта.

Раздельные токены для стейджа и прода; общие ключи заставляют эксперименты на стейдже сжигать прод-лимиты. Разные baseUrl по средам снижают человеческую ошибку «случайно указы на прод».

Когда TLS-инспекция на прокси переподписывает сертификаты, импортируйте корни в trust store сервисного пользователя, а не только администратора. Doctor может остаться зелёным, пока запросы падают с непрозрачной TLS-ошибкой.

Зафиксируйте, какие автоматизации могут вызывать поиск без человека в контуре, а какие требуют HITL-канала. Граница — в политике и наблюдаемости, не только в технологии.

Привяжите список разрешённых портов и протоколов к классификации данных: даже «только HTTPS» может расшириться административной ошибкой в конфиге прокси.

Как на практике различаются MCP, web_fetch и web_search

MCP расширяет инструменты через subprocess или HTTP-транспорт с независимой версионностью; подводные камни жизненного цикла — в материале про stdio и утечки. MCP уместен, когда нужны локальный ФС или специфичные бинарники.

web_search держите тонким HTTP-слоем с предсказуемыми квотами. Перегрузка поиска произвольной выборкой URL превращает его в неконтролируемый краулер без лимитов.

web_fetch, где доступен, несёт кэш, robots.txt и явные ограничения размера. Если ваш стек объединяет fetch и search, документируйте объединённую модель угроз.

После изменений — холодный рестарт, затем doctor и проверка канала по операционному ранбуку шлюза. Вопросы кромки TLS — в заметках про nginx/Caddy.

Сопоставьте политику кэширования: если fetch кэширует, а search — нет, инциденты «устаревший сниппет» будут выглядеть как баг модели, хотя корень в слое данных.

Глоссарий для эксплуатации поиска

tools.web.search — JSON-поддерево, описывающее HTTP-интеграцию поиска во многих сборках OpenClaw.

Пользовательский провайдер — любой бэкенд, который вы эксплуатируете или покупаете вместо демонстрационного по умолчанию.

Bearer-токен — секрет в заголовке Authorization; не должен появляться в argv и публичных логах.

Канареечный запрос — фиксированная тестовая фраза после выката для проверки задержки и авторизации без пользовательских данных.

Холодный рестарт — полная остановка процесса шлюза перед запуском, чтобы сбросить кэшированное состояние интеграций.

doctor — статическая проверка конфигурации и окружения; не заменяет мониторинг вендора в реальном времени.

SSRF — риск подделки серверных запросов, когда управляемые пользователем строки становятся URL.

Allowlist — перечень разрешённых имён хостов или CIDR для исходящего трафика.

429 — сигнал лимитирования; нужны бэкофф и алертинг.

Split-horizon DNS — разное разрешение одного имени внутри периметра и в публичном интернете.

Forward proxy — посредник исходящего HTTP с инспекцией и политиками.

mTLS — взаимная TLS-аутентификация между шлюзом и API поиска.

Квота — суточный или поминутный потолок запросов или расхода; по эффекту близка к throttling CPU.

Retry storm — лавина повторов клиента или модели на транзиентных ошибках.

Раздувание контекста — рост потребления токенов из-за чрезмерных сниппетов.

Паритет стейджа — идентичная форма интеграции со средой prod, отличаясь только эндпоинтами и ключами.

JSON schema в CI — линт конфигурации до merge, ловит опечатки в ключах.

Кардинальность метрик — держите в разумных пределах, маркируйте по среде, а не по каждой сессии чата.

Воспроизводитель инцидента — curl с редактированными секретами, показывающий первичную точку отказа.

Управляемый удалённый Mac — арендованное Apple-железо для шлюзов и SFTP-потоков артефактов.

Политика egress — документированный набор разрешённых хостов, портов и сценариев для автоматизации.

Ротация токенов — календарная смена секретов без простоя при схеме с двумя активными ключами.

Дрейф схемы — переименование ключей JSON при апгрейдах; ловится CI и регрессионными тестами.

Чёрный ящик снаружи — синтетика, которая бьёт в публичный путь, а не только в localhost.

Бюджет автоматизаций — потолок одновременных агентов с правом вызывать поиск в инциденте.

Аутентификация прокси — upstream username/password или SPNEGO, которые шлюз обязан предоставить для выхода в интернет.

Редакция логов — вычищение токенов и ПДн до отправки в сторонние системы журналирования.

Лёгкое CAB — короткая запись изменений для JSON, влияющего на egress или квоты.

Вопросы и связка с управляемым Mac

Резюме: Пользовательский web_search — это конфигурация плюс исходящая безопасность плюс наблюдаемость. Относитесь к интеграции как к прод-сервису, а не как к скрытой вкладке браузера.

Ограничения: Самостоятельные шлюзы наслаивают прокси, токены, диски и Apple-совместимые хосты сборки. Управляемый удалённый Mac SFTPMAC упаковывает аптайм и привычные паттерны доставки файлов, что хорошо стыкуется с долгоживущими OpenClaw-шлюзами, пока политика поиска эволюционирует.

Сохраняйте порядок чтения: лестница шлюза, жизненный цикл MCP, TLS-кромка, этот гайд по поиску, затем SSRF. В инциденте последовательность важнее новизны формулировок.