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 і
реєструють провайдерів, канали, інструменти, hooks або довірені середовища виконання.Що постачається сьогодні
@openclaw/sdk постачається з:
| Інтерфейс | Стан | Що він робить |
|---|---|---|
OpenClaw | Готово | Основна точка входу клієнта. Керує транспортом, з’єднанням, запитами та подіями. |
GatewayClientTransport | Готово | WebSocket-транспорт на базі клієнта Gateway. |
oc.agents | Готово | Перелічує, створює, оновлює, видаляє та отримує handles агентів. |
Agent.run() | Готово | Запускає виконання Gateway agent і повертає Run. |
oc.runs | Готово | Створює, отримує, очікує, скасовує та транслює виконання. |
Run.events() | Готово | Транслює нормалізовані події для окремого виконання з повтором для швидких виконань. |
Run.wait() | Готово | Викликає agent.wait і повертає стабільний RunResult. |
Run.cancel() | Готово | Викликає sessions.abort за id виконання, з ключем сесії, коли він доступний. |
oc.sessions | Готово | Створює, розв’язує, надсилає до, патчить, стискає та отримує handles сесій. |
Session.send() | Готово | Викликає sessions.send і повертає Run. |
oc.tasks | Готово | Перелічує, читає та скасовує записи журналу завдань Gateway. |
oc.models | Готово | Викликає models.list і поточний статусний RPC models.authStatus. |
oc.tools | Готово | Перелічує, задає scopes і викликає інструменти Gateway через конвеєр політик. |
oc.artifacts | Готово | Перелічує, отримує та завантажує артефакти транскриптів Gateway. |
oc.approvals | Готово | Перелічує та розв’язує схвалення exec через RPC схвалень Gateway. |
oc.environments | Частково | Перелічує локальні для Gateway та вузлові кандидати середовищ; create/delete ще не під’єднані. |
oc.rawEvents() | Готово | Надає сирі події Gateway для просунутих споживачів. |
normalizeGatewayEvent() | Готово | Перетворює сирі події Gateway на стабільну форму подій SDK. |
AgentRunParams, RunResult, RunStatus, OpenClawEvent,
OpenClawEventType, GatewayEvent, OpenClawTransport,
GatewayRequestOptions, SessionCreateParams, SessionSendParams,
ArtifactSummary, ArtifactQuery, ArtifactsListResult,
ArtifactsGetResult, ArtifactsDownloadResult,
TaskSummary, TaskStatus, TasksListParams, TasksListResult,
TasksGetResult, TasksCancelResult, RuntimeSelection,
EnvironmentSelection, WorkspaceSelection, ApprovalMode і пов’язані
типи результатів.
Під’єднання до Gateway
Створіть клієнт із явною URL-адресою Gateway або інжектуйте власний транспорт для тестів і вбудованих середовищ виконання застосунків.new OpenClaw({ gateway: "ws://..." }) еквівалентний url. Опцію
gateway: "auto" конструктор приймає, але автоматичне виявлення Gateway
ще не є окремою можливістю SDK; передавайте url, коли застосунок ще не
знає, як виявити Gateway.
Для тестів передайте об’єкт, який реалізує OpenClawTransport:
Запуск агента
Використовуйтеoc.agents.get(id), коли застосунку потрібен handle агента, а потім викличте
agent.run().
openai/gpt-5.5, розділяються на Gateway
override-и provider і model. timeoutMs у SDK залишається в мілісекундах і
перетворюється на секунди тайм-ауту Gateway для RPC agent.
run.wait() використовує RPC Gateway agent.wait. Дедлайн очікування, який спливає,
поки виконання ще активне, повертає status: "accepted", а не вдає,
що саме виконання вичерпало час. Тайм-аути середовища виконання, перервані виконання та скасовані виконання
нормалізуються до timed_out або cancelled.
Створення та повторне використання сесій
Використовуйте сесії, коли застосунку потрібен довговічний стан транскрипту.Session.send() викликає sessions.send і повертає Run. Handles сесій також
підтримують:
Трансляція подій
SDK нормалізує сирі події Gateway у стабільну оболонкуOpenClawEvent:
| Тип події | Вихідна подія Gateway |
|---|---|
run.started | Початок життєвого циклу agent |
run.completed | Завершення життєвого циклу agent |
run.failed | Помилка життєвого циклу agent |
run.cancelled | Завершення життєвого циклу після переривання/скасування |
run.timed_out | Завершення життєвого циклу через тайм-аут |
assistant.delta | Streaming delta асистента |
assistant.message | Повідомлення асистента |
thinking.delta | Thinking або потік плану |
tool.call.started | Початок інструмента/елемента/команди |
tool.call.delta | Оновлення інструмента/елемента/команди |
tool.call.completed | Завершення інструмента/елемента/команди |
tool.call.failed | Збій інструмента/елемента/команди або заблокований статус |
approval.requested | Запит схвалення exec або plugin |
approval.resolved | Розв’язання схвалення exec або plugin |
session.created | Створення sessions.changed |
session.updated | Оновлення sessions.changed |
session.compacted | Compaction sessions.changed |
task.updated | Події оновлення завдання |
artifact.updated | Події потоку patch |
raw | Будь-яка подія, що ще не має стабільного відображення SDK |
Run.events() фільтрує події до одного id виконання та повторює вже побачені події для
швидких виконань. Це означає, що документований потік безпечний:
oc.events(). Для сирих кадрів Gateway використовуйте
oc.rawEvents().
Моделі, інструменти, артефакти та схвалення
Помічники моделей відображаються на поточні методи Gateway:oc.tools.invoke() повертає типізовану оболонку замість
викидання винятку для відмов політики або схвалення.
sessionKey, runId або
taskId:
openclaw tasks:
Явно не підтримується сьогодні
SDK містить назви для моделі продукту, якої ми прагнемо, але не мовчки вдає, що RPC Gateway існують. Ці виклики зараз викидають явні помилки про непідтримуваність:workspace, runtime, environment і approvals типізовані
як майбутня форма, але поточний Gateway не підтримує ці override-и в
RPC agent. Якщо викликачі передають їх, SDK викидає помилку до надсилання виконання,
щоб робота випадково не виконалася з типовою поведінкою workspace, runtime,
environment або approval.
App SDK проти Plugin SDK
Використовуйте App SDK, коли код живе поза OpenClaw:- сценарії Node, які запускають або спостерігають виконання агентів
- завдання CI, які викликають Gateway
- панелі керування та адміністративні панелі
- розширення IDE
- зовнішні мости, яким не потрібно ставати channel plugins
- інтеграційні тести з фейковими або справжніми транспортами Gateway
- provider plugins
- channel plugins
- hooks інструментів або життєвого циклу
- plugins агентного harness
- довірені runtime-помічники
@openclaw/sdk. Код Plugin має імпортувати з
документованих підшляхів openclaw/plugin-sdk/*. Не змішуйте ці два контракти.