Skip to main content
Зовнішні застосунки взаємодіють з OpenClaw через протокол Gateway: транспорт WebSocket і методи RPC. Використовуйте його, коли скрипту, панелі моніторингу, завданню CI, розширенню IDE або іншому процесу потрібно запускати виконання агентів, потоково отримувати події, чекати на результати, скасовувати роботу або перевіряти ресурси Gateway.
Публічного клієнтського пакета npm поки немає. Не додавайте назви клієнтських пакетів OpenClaw до залежностей застосунку, доки в примітках до випуску не буде оголошено про опублікований пакет, а на цій сторінці не з’являться інструкції зі встановлення.
Ця сторінка призначена для коду поза процесом OpenClaw. Код Plugin, який виконується всередині OpenClaw, натомість має використовувати задокументовані підшляхи openclaw/plugin-sdk/*.

​
Що доступно зараз

Розроблення майбутнього пакета клієнтської бібліотеки триває внутрішньо, але він ще не є публічно доступним для встановлення. Вважайте його деталлю попередньої реалізації, доки у випуску не буде оголошено про опублікований версійований пакет.

​
Рекомендований підхід

  1. Запустіть або знайдіть Gateway.
  2. Підключіться через протокол Gateway.
  3. Викликайте задокументовані методи RPC з довідника RPC Gateway.
  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 перед підготовкою. Якщо шлях керування втрачено, зачекайте завершення двохвилинної оренди перед повторним підключенням; після завершення оренди приймання відновиться автоматично. Контракт 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. Готовий результат має такий вигляд:
Запит стану повертає {"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 .

​
Код застосунку й код Plugin

Використовуйте RPC Gateway, коли код працює поза OpenClaw:
  • скрипти Node, які запускають виконання агентів або спостерігають за ними
  • завдання CI, які викликають Gateway
  • панелі моніторингу та адміністрування
  • розширення IDE
  • зовнішні мости, яким не потрібно ставати Plugin каналів
  • інтеграційні тести з імітованими або реальними транспортами Gateway
Використовуйте SDK Plugin, коли код виконується всередині OpenClaw:
  • Plugin постачальників
  • Plugin каналів
  • перехоплювачі інструментів або життєвого циклу
  • Plugin середовища виконання агентів
  • довірені допоміжні засоби середовища виконання
Зовнішні застосунки не повинні імпортувати openclaw/plugin-sdk/*; ці підшляхи призначені для Plugin, які завантажує OpenClaw.

​
Пов’язані матеріали