OpenClaw App SDK — це публічний клієнтський API для застосунків поза процесом OpenClaw. ВикористовуйтеDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
@openclaw/sdk, коли скрипт, панель керування, завдання CI, розширення IDE
або інший зовнішній застосунок має підключатися до Gateway, запускати виконання агентів,
транслювати події, чекати на результати, скасовувати роботу або перевіряти ресурси Gateway.
App SDK відрізняється від Plugin SDK.
@openclaw/sdk взаємодіє з Gateway ззовні OpenClaw.
openclaw/plugin-sdk/* призначений лише для plugins, які працюють усередині OpenClaw і
реєструють провайдерів, канали, інструменти, хуки або довірені runtime-середовища.Що постачається сьогодні
@openclaw/sdk постачається з:
| Інтерфейс | Стан | Що він робить |
|---|---|---|
OpenClaw | Готово | Основна точка входу клієнта. Керує транспортом, підключенням, запитами та подіями. |
GatewayClientTransport | Готово | WebSocket-транспорт на основі клієнта Gateway. |
oc.agents | Готово | Перелічує, створює, оновлює, видаляє та отримує дескриптори агентів. |
Agent.run() | Готово | Запускає виконання Gateway agent і повертає Run. |
oc.runs | Готово | Створює, отримує, очікує, скасовує та транслює виконання. |
Run.events() | Готово | Транслює нормалізовані події для окремого виконання з повторним відтворенням для швидких виконань. |
Run.wait() | Готово | Викликає agent.wait і повертає стабільний RunResult. |
Run.cancel() | Готово | Викликає sessions.abort за id виконання, із ключем сесії, коли він доступний. |
oc.sessions | Готово | Створює, вирішує, надсилає до, виправляє, ущільнює та отримує дескриптори сесій. |
Session.send() | Готово | Викликає sessions.send і повертає Run. |
oc.models | Готово | Викликає models.list і поточний статусний RPC models.authStatus. |
oc.tools | Частково | Перелічує каталог інструментів і ефективні інструменти; прямий виклик інструментів не підключено. |
oc.approvals | Готово | Перелічує та вирішує схвалення виконання через RPC схвалень Gateway. |
oc.rawEvents() | Готово | Надає необроблені події Gateway для просунутих споживачів. |
normalizeGatewayEvent() | Готово | Перетворює необроблені події Gateway у стабільну форму подій SDK. |
AgentRunParams, RunResult, RunStatus, OpenClawEvent,
OpenClawEventType, GatewayEvent, OpenClawTransport,
GatewayRequestOptions, SessionCreateParams, SessionSendParams,
RuntimeSelection, EnvironmentSelection, WorkspaceSelection,
ApprovalMode і пов’язані типи результатів.
Підключення до Gateway
Створіть клієнт із явною URL-адресою Gateway або інжектуйте власний транспорт для тестів і runtime-середовищ вбудованих застосунків.new OpenClaw({ gateway: "ws://..." }) еквівалентний url. Параметр
gateway: "auto" приймається конструктором, але автоматичне виявлення Gateway
ще не є окремою функцією SDK; передавайте url, коли застосунок ще не знає,
як виявити Gateway.
Для тестів передайте об’єкт, який реалізує OpenClawTransport:
Запуск агента
Використовуйтеoc.agents.get(id), коли застосунку потрібен дескриптор агента, а потім викликайте
agent.run().
openai/gpt-5.5, розділяються на перевизначення Gateway
provider і model. timeoutMs залишається в мілісекундах у SDK і
перетворюється на секунди тайм-ауту Gateway для RPC agent.
run.wait() використовує RPC Gateway agent.wait. Якщо дедлайн очікування спливає,
поки виконання все ще активне, повертається status: "accepted" замість удавання,
що саме виконання вичерпало час. Тайм-аути runtime-середовища, перервані виконання та скасовані виконання
нормалізуються в timed_out або cancelled.
Створення та повторне використання сесій
Використовуйте сесії, коли застосунку потрібен сталий стан транскрипту.Session.send() викликає sessions.send і повертає Run. Дескриптори сесій також
підтримують:
Трансляція подій
SDK нормалізує необроблені події Gateway у стабільну оболонкуOpenClawEvent:
| Тип події | Вихідна подія Gateway |
|---|---|
run.started | Початок життєвого циклу agent |
run.completed | Завершення життєвого циклу agent |
run.failed | Помилка життєвого циклу agent |
run.cancelled | Завершення життєвого циклу після переривання/скасування |
run.timed_out | Завершення життєвого циклу через тайм-аут |
assistant.delta | Потокова дельта асистента |
assistant.message | Повідомлення асистента |
thinking.delta | Потік міркування або плану |
tool.call.started | Початок інструмента/елемента/команди |
tool.call.delta | Оновлення інструмента/елемента/команди |
tool.call.completed | Завершення інструмента/елемента/команди |
tool.call.failed | Збій інструмента/елемента/команди або заблокований статус |
approval.requested | Запит на схвалення виконання або Plugin |
approval.resolved | Рішення щодо схвалення виконання або Plugin |
session.created | Створення sessions.changed |
session.updated | Оновлення sessions.changed |
session.compacted | Ущільнення sessions.changed |
task.updated | Події оновлення завдань |
artifact.updated | Події потоку патчів |
raw | Будь-яка подія, що ще не має стабільного зіставлення SDK |
Run.events() фільтрує події до одного id виконання та повторно відтворює вже побачені події для
швидких виконань. Це означає, що задокументований потік безпечний:
oc.events(). Для необроблених кадрів Gateway використовуйте
oc.rawEvents().
Моделі, інструменти та схвалення
Допоміжні методи моделей зіставляються з поточними методами Gateway:Явно не підтримується сьогодні
SDK містить назви для моделі продукту, яку ми хочемо, але не вдає непомітно, що RPC Gateway існують. Наразі ці виклики викидають явні помилки непідтримуваності:workspace, runtime, environment і approvals для окремого виконання типізовані
як майбутня форма, але поточний Gateway не підтримує ці перевизначення в
RPC agent. Якщо викликачі передають їх, SDK викидає помилку до надсилання виконання,
щоб робота випадково не виконалася зі стандартною поведінкою workspace, runtime-середовища,
environment або схвалень.
App SDK і Plugin SDK
Використовуйте App SDK, коли код працює поза OpenClaw:- Node-скрипти, які запускають або спостерігають за виконаннями агентів
- завдання CI, які викликають Gateway
- панелі керування та адміністративні панелі
- розширення IDE
- зовнішні мости, яким не потрібно ставати канальними plugins
- інтеграційні тести з фіктивними або реальними транспортами Gateway
- plugins провайдерів
- канальні plugins
- інструментальні або життєво-циклові хуки
- plugins обв’язки агентів
- довірені допоміжні засоби runtime-середовища
@openclaw/sdk. Код Plugin має імпортувати з
задокументованих підшляхів openclaw/plugin-sdk/*. Не змішуйте ці два контракти.