OpenClaw API: внутренний клиент, токен Gateway и тест отказа

OpenClaw API во внутреннем клиенте строится вокруг одного маршрута Gateway, совместимого с форматом OpenAI: по умолчанию он выключен, а включается вручную в конфигурации. Токен к этому маршруту даёт права оператора, поэтому клиент ходит в Gateway через ваш серверный слой, а сотрудники видят только его. Сам Gateway видит за токеном одного оператора, поэтому разграничение ролей остаётся за вашим слоем.

Что открывает токен

Условный сценарий: в панели поддержки сотрудник просит агента OpenClaw собрать сводку по обращению. Панель отправляет запрос во внутренний сервис, сервис добавляет токен Gateway и пересылает вызов. Сам Gateway, по документации по безопасности, рассчитан на одну границу доверия: одного оператора или команду, которая доверяет друг другу. Документация прямо называет действующий токен или пароль для этого маршрута учётными данными владельца или оператора, а отдельной узкой привилегии для пользователя нет. Раздать такой ключ каждому клиентскому приложению значит раздать административный доступ.

Здесь разбирается клиент, который вызывает уже работающий Gateway. Установка узла, каналы мессенджеров и пары устройств остаются за рамками. Если вы выбираете между своим сервером и облаком, начните с разбора локального ИИ-агента: он показывает, какие данные остаются внутри периметра. Привычки из других сервисов переносите осторожно: у Open WebUI есть собственное API для внутренних сервисов со своей моделью ключей, и перенос этой модели на OpenClaw ломает границы доступа.

Запишите контракт до первой строки кода: кто вызывает, какого агента, какие поля уходят, где лежит токен и кто читает журнал. Хватит одного абзаца на каждый пункт. Без такой записи сервис быстро обрастает исключениями, а токен оказывается в браузере, в скрипте аналитика и в чате команды.

Включение маршрута

Маршрут чата отключён по умолчанию. В конфигурации Gateway его включает параметр gateway.http.endpoints.chatCompletions.enabled со значением true. После этого на порту Gateway отвечают четыре маршрута: POST /v1/chat/completions, GET /v1/models, GET /v1/models/{id} и POST /v1/embeddings; их перечень приведён на странице OpenAI Chat Completions. Все четыре работают под одним токеном, и клиенту для чата нужны первые два. Остальные закрываются на серверном слое.

1. Оставьте привязку Gateway к loopback, как в настройках по умолчанию, и открывайте порт только адресу внутреннего сервиса на уровне сети.
2. Выберите режим аутентификации token. Значение положите в менеджер секретов или в переменную OPENCLAW_GATEWAY_TOKEN серверного процесса.
3. Включите маршрут чата в конфигурации и проверьте, что он ожидаемо отвечает: до включения вызов получает отказ, после включения запрос со списком моделей проходит.
4. Запросите GET /v1/models с заголовком Authorization: Bearer и сохраните ответ в журнал теста как эталон списка целей.

Отдельно решите, кто владеет токеном. Владельцем назначают одного конкретного человека, он отвечает за ротацию, за запись об изменении и за отзыв при подозрении на утечку. Ротацию проводят с проверкой нового значения до удаления старого, иначе внутренний клиент останавливается посреди рабочего дня. Серверный слой читает токен при старте и при каждом обновлении секрета, поэтому смена значения проходит без правки кода.

Режим none без заголовка авторизации допустим только для закрытого входа в сеть, поэтому для клиента компании берите token или password. После правки конфигурации прогоните openclaw security audit: эта команда из раздела безопасности сверяет настройки с рекомендованными и показывает дрейф. Результат аудита приложите к записи об изменении, чтобы следующий администратор видел, кто и зачем открыл маршрут.

Выбор агента

Поле model в запросе к этому маршруту называет цель-агента, а модель провайдера тут вообще другая сущность. Значение openclaw ведёт к агенту по умолчанию, openclaw/default служит устойчивым псевдонимом, openclaw/<agentId> выбирает конкретного агента. Выбор модели под агентом лежит на стороне Gateway и в этой статье остаётся за скобками.

• Клиент передаёт короткое имя роли, например «поддержка» или «аналитика». Серверный слой превращает его в идентификатор агента по таблице, которую ведёте вы.
• Заголовок x-openclaw-model переопределяет модель за агентом, и для вызывающих с идентичностью требует права operator.admin. Слой отбрасывает его и пересылает дальше только разрешённое.
• Вызов без памяти работает по умолчанию. Поле user создаёт устойчивую сессию, а x-openclaw-session-key задаёт ключ явно. Ключ формирует слой из идентификатора сотрудника, а клиентское значение игнорируется.
• Функции инструментов в формате OpenAI передаются дальше только для агентов, где такой набор согласован заранее.

Разделение простое: полные данные обрабатывает ваш скрипт, агент объясняет и предлагает, сотрудник сверяет результат с карточкой. Права на запись в учётных системах проверяет сервер при каждом действии, а текст агента остаётся предложением. Так граница доверия Gateway остаётся целой, хотя внутри компании запросы идут от разных людей.

Тест отказа

Проверка успешного вызова отвечает на вопрос «работает ли связка». Тест отказа отвечает на вопрос «что ломается, когда клиент ведёт себя плохо». Gateway сам возвращает ошибку авторизации, а роли, белый список агентов и ограничение маршрутов обеспечивает ваш слой, потому что роли вашей компании описаны только в вашем слое. Коды ответов берите из собственного прогона и записывайте в журнал теста.

Отличайте настоящий запрет от ошибки конфигурации. Если отказ пришёл при верном токене, сначала откройте журнал Gateway и проверьте включение маршрута, режим аутентификации и значение переменной окружения. Повторяйте весь список после каждого обновления Gateway: права маршрута могут измениться вместе с версией.

Журнал и допуск

Журнал серверного слоя собирает сведения о сотрудниках, которых у Gateway нет: время, сотрудника, роль, идентификатор агента, технический идентификатор вызова, статус и длительность. Текст запроса, текст ответа и значение токена исключите из записи. Для разбора инцидента хватает ссылки на карточку в исходной системе, доступную тем, у кого есть право её открыть. Срок хранения журнала задаёт владелец процесса, а читают его двое: администратор слоя и ответственный за безопасность.

Остановку вызовов отрепетируйте до пилота. У слоя должен быть выключатель на роль и общий выключатель на все роли; оба срабатывают без перезапуска Gateway. Проверка выглядит так: включите выключатель, повторите вызов сотрудника и убедитесь, что слой отвечает отказом, а в журнале появилась запись о причине. Только после этого можно приглашать пользователей, потому что в первый же день кто-нибудь пришлёт агенту нестандартный запрос.

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

Частые вопросы