RPC and API

Интеграции Gateway с внешними приложениями

Внешние приложения взаимодействуют с OpenClaw через протокол Gateway: транспорт WebSocket и методы RPC. Используйте его, когда скрипту, панели мониторинга, заданию CI, расширению IDE или другому процессу требуется запускать выполнения агента, передавать события в потоке, ожидать результаты, отменять работу или проверять ресурсы Gateway.

Что доступно сейчас

Поверхность	Статус	Назначение
Протокол Gateway	Готово	Транспорт WebSocket, установление соединения, области авторизации, версионирование протокола и события.
Справочник RPC Gateway	Готово	Текущие методы Gateway для агентов, сеансов, задач, моделей, инструментов, артефактов и подтверждений.
`openclaw agent`	Готово	Однократная интеграция со скриптом, когда достаточно вызова CLI через оболочку.
`openclaw message`	Готово	Отправка сообщений или действий канала из скриптов.

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

Согласованная приостановка хоста

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

Прекратите приём внешнего входящего трафика, контролируемого хостом.
Вызовите gateway.suspend.prepare со стабильным уникальным requestId.
Если ответ — busy, оставьте процесс запущенным и повторите попытку позже.
Если ответ — ready, сохраните возвращённый suspensionId, затем заморозьте процесс или создайте его снимок до expiresAtMs.
После размораживания или при отказе от приостановки вызовите gateway.suspend.resume с этим suspensionId через существующий WebSocket или управляющий канал Admin HTTP.

Подготовленный Gateway отклоняет новые установления соединений WebSocket. Контроллер WebSocket должен сохранять своё аутентифицированное соединение открытым на протяжении операции хоста. Если это невозможно гарантировать, перед подготовкой включите и используйте плагин RPC Admin HTTP. Если управляющий канал потерян, подождите истечения двухминутной аренды перед повторным подключением; после истечения срока приём автоматически возобновляется.

Контракт RPC:

gateway.suspend.prepare — operator.admin; параметры { "requestId": "stable-host-operation-id" }
gateway.suspend.status — operator.read; параметры { "suspensionId": "id-from-prepare" }
gateway.suspend.resume — operator.admin; параметры { "suspensionId": "id-from-prepare" }

Пробелы по краям идентификаторов удаляются; идентификаторы должны содержать непробельный символ, а их длина ограничена 128 символами. Результат занятой подготовки содержит status: "busy", reason, retryAfterMs, activeCount и blockers. Готовый результат имеет следующий вид:

json

{  "status": "ready",  "suspensionId": "2c3f...",  "expiresAtMs": 1770000000000,  "activeCount": 0,  "blockers": []}

Запрос статуса возвращает {"status":"running"} или готовый результат с expiresAtMs. Возобновление возвращает {"ok":true,"status":"running","resumed":true}; повторный вызов после успешного возобновления возвращает resumed: false.

Конкурирующий идентификатор запроса или временный сбой возобновления планировщика возвращает допускающую повторную попытку ошибку UNAVAILABLE с retryAfterMs. Во время восстановления планировщика подготовка, проверка статуса и возобновление возвращают эту ошибку, Gateway остаётся неготовым и работает в закрытом при сбое режиме, а хост не должен замораживать его или создавать его снимок. OpenClaw автоматически повторяет попытки восстановления планировщика и возобновляет приём только после успешного восстановления. При несовпадении идентификатора возобновления возвращается INVALID_REQUEST. Подготовка использует общий бюджет операций записи плоскости управления Gateway — три попытки в минуту; соблюдайте возвращённую задержку повторной попытки. Клиенты WebSocket распределяются по группам на основе устройства и IP-адреса. Контроллеры Admin HTTP распределяются по группам на основе определённого IP-адреса клиента, поэтому контроллеры за одним прокси-сервером могут использовать общий бюджет.

Подготовка работает только через отказ: OpenClaw закрывает приём новых корневых операций, операций сеансов и команд, приостанавливает автоматические такты cron и синхронно проверяет работу. Если что-либо активно, он возобновляет планировщик и открывает приём перед возвратом busy; он не прерывает эту работу и не ожидает её завершения. Срок готовой аренды — две минуты. Повторный вызов prepare с тем же requestId продлевает её; по истечении срока планировщик возобновляется до открытия приёма. Событие перезапуска, срок которого наступил во время готовой аренды, ожидает возобновления аренды; выполняющийся перезапуск приводит к возврату busy при подготовке.

В состоянии готовности /healthz остаётся активным, а /readyz возвращает 503. Локальные или аутентифицированные ответы о готовности содержат gateway-draining; неаутентифицированные удалённые проверки получают только { "ready": false }. HTTP-проверка работоспособности, методы приостановки в существующих соединениях WebSocket и уже включённый маршрут RPC Admin HTTP остаются доступными. Другие вызовы RPC возвращают допускающую повторную попытку ошибку UNAVAILABLE. Встроенные пользовательские рабочие маршруты HTTP и обычные HTTP-маршруты плагинов, включая API, совместимые с OpenAI, операции с инструментами и сеансами, наблюдение за узлами и настроенные хуки, возвращают 503 с error.code: "gateway_unavailable". Новые принадлежащие плагинам обновления соединения WebSocket также возвращают 503; это относится к владению обновлением соединения, а не к работе, выполняемой позднее через уже установленный сокет плагина.

Это согласование не сохраняет входящие сообщения, не останавливает транспорты сторонних каналов и не управляет платформой хостинга. Хост должен оградить свой входящий трафик перед подготовкой и по-прежнему отвечает за пробуждение, создание снимка или заморозку и остановку. activeCount — совокупное количество отслеживаемых работ, а blockers содержит ненулевые количества по категориям и ограниченные сведения о задачах. Это не универсальный барьер перехода процесса в состояние покоя. Блокировщик background-exec содержит только агрегированные сведения: текст команд, идентификаторы процессов, вывод, а также идентификаторы сеансов или областей никогда не передаются через протокол. Проверки работоспособности каналов, обслуживание, обновление кеша, установленные сеансы WebSocket плагинов и незарегистрированная фоновая работа, принадлежащая плагинам, могут оставаться активными. Платформа хостинга должна согласованно замораживать или создавать снимок всего дерева процессов и его файловой системы; этот первоначальный контракт не позволяет доказать, что незарегистрированная работа простаивает.

Код приложения и код плагина

Используйте RPC Gateway, когда код находится вне OpenClaw:

скрипты Node, запускающие или отслеживающие выполнения агентов
задания CI, вызывающие Gateway
панели мониторинга и административные панели
расширения IDE
внешние мосты, которым не требуется становиться плагинами каналов
интеграционные тесты с имитируемыми или реальными транспортами Gateway

Используйте Plugin SDK, когда код выполняется внутри OpenClaw:

плагины провайдеров
плагины каналов
инструменты или хуки жизненного цикла
плагины среды выполнения агента
доверенные вспомогательные средства среды выполнения

Внешние приложения не должны импортировать openclaw/plugin-sdk/*; эти подпути предназначены для плагинов, загружаемых OpenClaw.

Связанные материалы

Was this useful?