---
read_when:
- Вы создаёте внешнее приложение, скрипт, панель мониторинга, задание CI или расширение IDE, которое взаимодействует с OpenClaw
- Вы выбираете между RPC Gateway и SDK плагинов
- Вы интегрируетесь с запусками агентов Gateway, сеансами, событиями, подтверждениями, моделями или инструментами
- Вы связываете контроллер хостинга с внешним планировщиком пробуждения
sidebarTitle: External apps
summary: Текущий путь интеграции для внешних приложений, скриптов, панелей мониторинга, заданий CI и расширений IDE
title: Интеграции Gateway с внешними приложениями
x-i18n:
generated_at: "2026-07-13T18:07:49Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 24
provider: openai
source_hash: 0034db64dea64f8c5c400cf2adc69c6e046d0cd574914fe7497099018cb28745
source_path: gateway/external-apps.md
workflow: 16
---
Внешние приложения взаимодействуют с OpenClaw через протокол Gateway: транспорт
WebSocket и методы RPC. Используйте его, когда скрипту, панели мониторинга, заданию CI,
расширению IDE или другому процессу требуется запускать выполнения агента, передавать события
в потоке, ожидать результаты, отменять работу или проверять ресурсы Gateway.
Общедоступного клиентского пакета npm пока нет. Не добавляйте имена клиентских пакетов
OpenClaw в зависимости приложения, пока в примечаниях к выпуску не будет объявлено об
опубликованном пакете, а на этой странице не появятся инструкции по установке.
Эта страница предназначена для кода вне процесса OpenClaw. Код плагина, выполняющийся
внутри OpenClaw, должен вместо этого использовать документированные подпути `openclaw/plugin-sdk/*`.
## Что доступно сейчас
| Поверхность | Статус | Назначение |
| --------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| [Протокол Gateway](/ru/gateway/protocol) | Готово | Транспорт WebSocket, установление соединения, области авторизации, версионирование протокола и события. |
| [Справочник RPC Gateway](/ru/reference/rpc) | Готово | Текущие методы Gateway для агентов, сеансов, задач, моделей, инструментов, артефактов и подтверждений. |
| [`openclaw agent`](/ru/cli/agent) | Готово | Однократная интеграция со скриптом, когда достаточно вызова CLI через оболочку. |
| [`openclaw message`](/ru/cli/message) | Готово | Отправка сообщений или действий канала из скриптов. |
Работа над будущим пакетом клиентской библиотеки ведётся внутри проекта, но пока это не
общедоступная поверхность установки. Считайте его предварительной деталью реализации, пока
в выпуске не будет объявлен опубликованный версионируемый пакет.
## Рекомендуемый путь
1. Запустите или обнаружьте Gateway.
2. Подключитесь через [протокол Gateway](/ru/gateway/protocol).
3. Вызывайте документированные методы RPC из [справочника RPC Gateway](/ru/reference/rpc).
4. Зафиксируйте версию OpenClaw, с которой проводите тестирование.
5. При обновлении OpenClaw повторно сверяйтесь со справочником RPC.
Для выполнения агентов начните с RPC `agent` и используйте его вместе с `agent.wait`,
чтобы получить итоговый результат. Для долговременного состояния диалога используйте методы `sessions.*`.
В интеграциях с пользовательским интерфейсом подпишитесь на события Gateway и отображайте только
те семейства событий, которые понимает ваше приложение.
## Согласованная приостановка хоста
Контроллеры хостинга, замораживающие или создающие снимок выполняющегося процесса, могут
использовать независимое от хоста согласование приостановки:
1. Прекратите приём внешнего входящего трафика, контролируемого хостом.
2. Вызовите `gateway.suspend.prepare` со стабильным уникальным `requestId`.
3. Если ответ — `busy`, оставьте процесс запущенным и повторите попытку позже.
4. Если ответ — `ready`, сохраните возвращённый `suspensionId`, затем заморозьте процесс
или создайте его снимок до `expiresAtMs`.
5. После размораживания или при отказе от приостановки вызовите `gateway.suspend.resume`
с этим `suspensionId` через существующий WebSocket или управляющий канал Admin HTTP.
Подготовленный Gateway отклоняет новые установления соединений WebSocket. Контроллер WebSocket
должен сохранять своё аутентифицированное соединение открытым на протяжении операции хоста. Если
это невозможно гарантировать, перед подготовкой включите и используйте
[плагин RPC Admin HTTP](/ru/plugins/admin-http-rpc). Если управляющий канал потерян, подождите
истечения двухминутной аренды перед повторным подключением; после истечения срока приём
автоматически возобновляется.
Контракт 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
плагинов и незарегистрированная фоновая работа, принадлежащая плагинам, могут оставаться активными.
Платформа хостинга должна согласованно замораживать или создавать снимок всего дерева процессов
и его файловой системы; этот первоначальный контракт не позволяет доказать, что
незарегистрированная работа простаивает.
Для планирования пробуждения хоста оставьте связанную с OpenClaw часть во внутрипроцессном
плагине и передавайте идемпотентные полные снимки внешнему адаптеру хоста.
Контроллер хостинга не должен импортировать Plugin SDK или восстанавливать состояние cron
по изменениям событий. См. [Безопасная внешняя проекция
cron](/ru/plugins/hooks#safe-external-cron-projection).
## Код приложения и код плагина
Используйте RPC Gateway, когда код находится вне OpenClaw:
- скрипты Node, запускающие или отслеживающие выполнения агентов
- задания CI, вызывающие Gateway
- панели мониторинга и административные панели
- расширения IDE
- внешние мосты, которым не требуется становиться плагинами каналов
- интеграционные тесты с имитируемыми или реальными транспортами Gateway
Используйте Plugin SDK, когда код выполняется внутри OpenClaw:
- плагины провайдеров
- плагины каналов
- инструменты или хуки жизненного цикла
- плагины среды выполнения агента
- доверенные вспомогательные средства среды выполнения
Внешние приложения не должны импортировать `openclaw/plugin-sdk/*`; эти подпути предназначены
для плагинов, загружаемых OpenClaw.
## Связанные материалы
- [Протокол Gateway](/ru/gateway/protocol)
- [Справочник RPC Gateway](/ru/reference/rpc)
- [Команда агента CLI](/ru/cli/agent)
- [Команда сообщения CLI](/ru/cli/message)
- [Цикл агента](/ru/concepts/agent-loop)
- [Среды выполнения агентов](/ru/concepts/agent-runtimes)
- [Сеансы](/ru/concepts/session)
- [Фоновые задачи](/ru/automation/tasks)
- [Агенты ACP](/ru/tools/acp-agents)
- [Обзор Plugin SDK](/ru/plugins/sdk-overview)