---
read_when:
- Ви створюєте зовнішній застосунок, скрипт, панель керування, завдання CI або розширення IDE, що взаємодіє з OpenClaw
- Ви обираєте між Gateway RPC і Plugin SDK
- Ви інтегруєтеся із запусками агентів, сеансами, подіями, схваленнями, моделями або інструментами Gateway
- Ви пов’язуєте контролер хостингу із зовнішнім планувальником пробудження
sidebarTitle: External apps
summary: Поточний шлях інтеграції для зовнішніх застосунків, скриптів, інформаційних панелей, завдань CI та розширень IDE
title: Інтеграції Gateway із зовнішніми застосунками
x-i18n:
generated_at: "2026-07-12T13:15:17Z"
model: gpt-5.6
postprocess_version: locale-links-v1
provider: openai
source_hash: 0034db64dea64f8c5c400cf2adc69c6e046d0cd574914fe7497099018cb28745
source_path: gateway/external-apps.md
workflow: 16
---
Зовнішні застосунки взаємодіють з OpenClaw через протокол Gateway: транспорт
WebSocket і методи RPC. Використовуйте його, коли скрипту, панелі моніторингу,
завданню CI, розширенню IDE або іншому процесу потрібно запускати виконання
агентів, потоково отримувати події, чекати на результати, скасовувати роботу
або перевіряти ресурси Gateway.
Публічного клієнтського пакета npm поки немає. Не додавайте назви
клієнтських пакетів OpenClaw до залежностей застосунку, доки в примітках до
випуску не буде оголошено про опублікований пакет, а на цій сторінці не
з’являться інструкції зі встановлення.
Ця сторінка призначена для коду поза процесом OpenClaw. Код Plugin, який
виконується всередині OpenClaw, натомість має використовувати
задокументовані підшляхи `openclaw/plugin-sdk/*`.
## Що доступно зараз
| Інтерфейс | Стан | Призначення |
| -------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| [Протокол Gateway](/uk/gateway/protocol) | Готово | Транспорт WebSocket, установлення з’єднання, області автентифікації, версіювання протоколу та події. |
| [Довідник RPC Gateway](/uk/reference/rpc) | Готово | Поточні методи Gateway для агентів, сеансів, завдань, моделей, інструментів, артефактів і погоджень. |
| [`openclaw agent`](/uk/cli/agent) | Готово | Одноразова інтеграція зі скриптом, коли достатньо викликати CLI через оболонку. |
| [`openclaw message`](/uk/cli/message) | Готово | Надсилання повідомлень або дій каналу зі скриптів. |
Розроблення майбутнього пакета клієнтської бібліотеки триває внутрішньо, але
він ще не є публічно доступним для встановлення. Вважайте його деталлю
попередньої реалізації, доки у випуску не буде оголошено про опублікований
версійований пакет.
## Рекомендований підхід
1. Запустіть або знайдіть Gateway.
2. Підключіться через [протокол Gateway](/uk/gateway/protocol).
3. Викликайте задокументовані методи RPC з [довідника RPC Gateway](/uk/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 має тримати своє автентифіковане з’єднання відкритим
протягом операції хоста. Якщо гарантувати це неможливо, увімкніть і
використовуйте [Plugin RPC Admin HTTP](/uk/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-маршрути Plugin, зокрема API, сумісні з OpenAI, операції з
інструментами й сеансами, спостереження за вузлами та налаштовані перехоплювачі,
повертають `503` з `error.code: "gateway_unavailable"`. Нові оновлення
WebSocket, що належать Plugin, також повертають `503`; це стосується володіння
оновленням, а не роботи, яка згодом виконується через уже встановлений сокет
Plugin.
Цей протокол не зберігає вхідні повідомлення, не зупиняє сторонні транспорти
каналів і не керує платформою хостингу. Хост має ізолювати свій вхідний трафік
до підготовки та залишається відповідальним за пробудження, створення
знімка/заморожування й зупинення. `activeCount` — це сукупна кількість
відстежуваної роботи, а `blockers` містить ненульові кількості за категоріями
та обмежені відомості про завдання. Це не загальний бар’єр досягнення стану
спокою процесу. Блокувальник `background-exec` містить лише сукупні дані:
текст команд, ідентифікатори процесів, вивід, а також ідентифікатори сеансів
або областей ніколи не передаються через протокол. Перевірка справності
каналів, обслуговування, оновлення кешу, установлені сеанси WebSocket Plugin і
незареєстрована фонова робота, що належить Plugin, можуть залишатися активними.
Платформа хостингу має узгоджено заморожувати або створювати знімок усього
дерева процесів і його файлової системи; цей початковий контракт не може
підтвердити бездіяльність незареєстрованої роботи.
Для планування пробудження хоста залишайте частину, орієнтовану на OpenClaw,
у внутрішньопроцесному Plugin і передавайте ідемпотентні повні знімки
зовнішньому адаптеру хоста. Контролер хостингу не повинен імпортувати SDK
Plugin або відтворювати стан cron за дельтами подій. Див.
[Безпечне зовнішнє проєктування cron
](/uk/plugins/hooks#safe-external-cron-projection).
## Код застосунку й код Plugin
Використовуйте RPC Gateway, коли код працює поза OpenClaw:
- скрипти Node, які запускають виконання агентів або спостерігають за ними
- завдання CI, які викликають Gateway
- панелі моніторингу та адміністрування
- розширення IDE
- зовнішні мости, яким не потрібно ставати Plugin каналів
- інтеграційні тести з імітованими або реальними транспортами Gateway
Використовуйте SDK Plugin, коли код виконується всередині OpenClaw:
- Plugin постачальників
- Plugin каналів
- перехоплювачі інструментів або життєвого циклу
- Plugin середовища виконання агентів
- довірені допоміжні засоби середовища виконання
Зовнішні застосунки не повинні імпортувати `openclaw/plugin-sdk/*`; ці
підшляхи призначені для Plugin, які завантажує OpenClaw.
## Пов’язані матеріали
- [Протокол Gateway](/uk/gateway/protocol)
- [Довідник RPC Gateway](/uk/reference/rpc)
- [Команда агента CLI](/uk/cli/agent)
- [Команда повідомлення CLI](/uk/cli/message)
- [Цикл агента](/uk/concepts/agent-loop)
- [Середовища виконання агентів](/uk/concepts/agent-runtimes)
- [Сеанси](/uk/concepts/session)
- [Фонові завдання](/uk/automation/tasks)
- [Агенти ACP](/uk/tools/acp-agents)
- [Огляд SDK Plugin](/uk/plugins/sdk-overview)