From 28a192e600c24f8a217b4a75ae89625d8d19badb Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 30 Apr 2026 00:51:01 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/concepts/openclaw-sdk.md | 313 +++++++------- docs/uk/plugins/sdk-overview.md | 412 ++++++++++--------- docs/uk/reference/openclaw-sdk-api-design.md | 237 ++++++----- 3 files changed, 503 insertions(+), 459 deletions(-) diff --git a/docs/uk/concepts/openclaw-sdk.md b/docs/uk/concepts/openclaw-sdk.md index eb2157127..c5d01f350 100644 --- a/docs/uk/concepts/openclaw-sdk.md +++ b/docs/uk/concepts/openclaw-sdk.md @@ -1,119 +1,126 @@ --- read_when: - - Ви проєктуєте або реалізуєте публічний SDK для застосунків OpenClaw - - Ви порівнюєте API агентів OpenClaw з Cursor, Claude Agent SDK, OpenAI Agents, Google ADK, OpenCode, Codex або ACP - - Потрібно визначити, чи належить можливість до публічного SDK застосунку, Plugin SDK, протоколу Gateway, бекенду ACP або шару керованого середовища -summary: Проєктна пропозиція щодо публічного SDK застосунків OpenClaw для запусків агентів, сеансів, завдань, артефактів і керованих середовищ -title: Дизайн SDK OpenClaw + - Ви проєктуєте або реалізуєте публічний SDK застосунку OpenClaw + - Ви порівнюєте API агентів OpenClaw із Cursor, Claude Agent SDK, OpenAI Agents, Google ADK, OpenCode, Codex або ACP + - Потрібно вирішити, чи належить можливість до публічного App SDK, Plugin SDK, протоколу Gateway, бекенду ACP або шару керованого середовища +sidebarTitle: App SDK +summary: Дизайн публічного SDK застосунків OpenClaw для зовнішніх застосунків, скриптів, панелей моніторингу, завдань CI та розширень IDE +title: SDK застосунків OpenClaw x-i18n: - generated_at: "2026-04-29T23:55:40Z" + generated_at: "2026-04-30T00:49:49Z" model: gpt-5.5 provider: openai - source_hash: ffd4380e556e0e2e1218acaa9e5934e8b308b3420aa25a6d2598d35c7f9a7ab2 + source_hash: 227d3baf3aaf54bf35288214b051e2e284280165e1283d476594feda26d56bb9 source_path: concepts/openclaw-sdk.md workflow: 16 --- -Ця сторінка є проєктною пропозицією для майбутнього публічного **SDK застосунків OpenClaw**. Вона -окрема від наявного [Plugin SDK](/uk/plugins/sdk-overview). +Ця сторінка є проєктною пропозицією для публічного **OpenClaw App SDK**. Вона +відокремлена від наявного [Plugin SDK](/uk/plugins/sdk-overview). -Plugin SDK призначений для коду, який виконується всередині OpenClaw і розширює провайдерів, -канали, інструменти, хуки та довірені середовища виконання. SDK застосунків має бути призначений для -зовнішніх застосунків, скриптів, інформаційних панелей, завдань CI, розширень IDE та -систем автоматизації, які хочуть запускати й спостерігати за агентами OpenClaw через стабільний + + Використовуйте `@openclaw/sdk`, коли зовнішній застосунок, скрипт, dashboard, CI job або IDE + extension хоче запускати агентів OpenClaw і спостерігати за ними через Gateway. Використовуйте + `openclaw/plugin-sdk/*` лише під час написання Plugin, який працює всередині OpenClaw. + + +Plugin SDK призначений для коду, який працює всередині OpenClaw і розширює providers, +channels, tools, hooks і trusted runtimes. App SDK має бути призначений для +зовнішніх застосунків, скриптів, dashboards, CI jobs, IDE extensions і +систем автоматизації, які хочуть запускати агентів OpenClaw і спостерігати за ними через стабільний публічний API. ## Статус Чернетка архітектури. -Цей документ фіксує напрям дизайну з порівняльного огляду цих -SDK агентів і поверхонь середовища виконання: +Цей документ фіксує напрям дизайну на основі порівняльного огляду цих +agent SDK і runtime surfaces: | Проєкт | Корисний висновок | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Cursor SDK cookbook | Найкращий високорівневий продуктовий API: `Agent`, `Run`, локальні та хмарні середовища виконання, потокова передача, скасування, виявлення моделей, репозиторії, артефакти та хмарні потоки pull request. | -| Claude Agent SDK | Сильний двонапрямний клієнт сесії, підтримка переривання й керування, режими дозволів, хуки, користувацькі інструменти, сховища сесій і відновлювані транскрипти. | -| OpenAI Agents SDK | Сильні концепції робочих процесів: передавання керування, запобіжники, людські схвалення, трасування, стан запуску, об’єкти результатів потокової передачі та відновлення після переривань. | -| Google ADK | Сильна внутрішня архітектура: runner, сервіс сесій, сервіс пам’яті, сервіс артефактів, сервіс облікових даних, Plugins, дії подій і підтвердження довготривалих інструментів. | -| OpenCode | Сильна форма клієнт/сервер: згенерований API-клієнт, REST плюс SSE, сесії, робочі простори, worktrees, дозволи, запитання, файли, VCS, PTY, інструменти, агенти, Skills і MCP. | -| Codex | Сильна межа локального середовища виконання: схвалення, ізоляція sandbox, мережева політика, локальні та віддалені сервери exec, структуровані події протоколу та сесії app-server з урахуванням тредів. | -| ACP and acpx | Сильний шар взаємодії для зовнішніх coding harnesses з іменованими сесіями, чергами підказок, кооперативним скасуванням і адаптерами середовища виконання. | +| Cursor SDK cookbook | Найкращий високорівневий продуктовий API: `Agent`, `Run`, локальні та хмарні runtimes, streaming, cancellation, model discovery, repositories, artifacts і cloud pull request flows. | +| Claude Agent SDK | Потужний двоспрямований session client, підтримка interrupt і steer, permission modes, hooks, custom tools, session stores і resumable transcripts. | +| OpenAI Agents SDK | Сильні концепції workflow: handoffs, guardrails, human approvals, tracing, run state, streaming result objects і resume after interruptions. | +| Google ADK | Потужна внутрішня архітектура: runner, session service, memory service, artifact service, credential service, plugins, event actions і long running tool confirmations. | +| OpenCode | Сильна форма client/server: generated API client, REST plus SSE, sessions, workspaces, worktrees, permissions, questions, files, VCS, PTY, tools, agents, skills і MCP. | +| Codex | Сильна межа локального runtime: approvals, sandboxing, network policy, локальні та віддалені exec servers, structured protocol events і thread aware app-server sessions. | +| ACP і acpx | Сильний шар сумісності для зовнішніх coding harnesses із named sessions, prompt queues, cooperative cancellation і runtime adapters. | -Рекомендація полягає в тому, щоб побудувати простий, як у Cursor, публічний фасад поверх -згенерованого клієнта Gateway у стилі OpenCode, зберігаючи концепції Claude, OpenAI Agents, -ADK, Codex і ACP як внутрішні проєктні орієнтири там, де вони доречні. +Рекомендація полягає в тому, щоб побудувати публічний facade у стилі Cursor-simple поверх +згенерованого Gateway client у стилі OpenCode, зберігаючи концепції Claude, OpenAI Agents, +ADK, Codex і ACP як внутрішні дизайнерські орієнтири там, де вони доречні. ## Цілі -- Надати розробникам застосунків мінімальний високорівневий API для запуску агентів OpenClaw. -- Зберегти локальний за замовчуванням OpenClaw як стандартне середовище виконання. -- Зробити хмарні або керовані середовища додатковим провайдером середовища, а не - іншим API агента. -- Зберегти наявні межі OpenClaw: Gateway володіє публічним протоколом, Plugin - SDK володіє внутрішньопроцесними розширеннями, ACP володіє взаємодією із зовнішніми harnesses. -- Підтримувати `stream`, `wait`, `cancel`, `resume`, `fork`, артефакти, схвалення - та фонові завдання як першокласні операції. -- Надавати стабільні нормалізовані події, зберігаючи водночас сирі події, нативні для середовища виконання, для +- Дати розробникам застосунків мінімальний високорівневий API для запуску агентів OpenClaw. +- Зберегти local-first OpenClaw як runtime за замовчуванням. +- Зробити хмарні або managed environments додатковим environment provider, а не + іншим agent API. +- Зберегти наявні межі OpenClaw: Gateway володіє публічним protocol, plugin + SDK володіє in-process extensions, ACP володіє interop із external harness. +- Підтримувати `stream`, `wait`, `cancel`, `resume`, `fork`, artifacts, approvals, + і background tasks як першокласні операції. +- Надавати стабільні нормалізовані events, зберігаючи runtime-native raw events для просунутих споживачів. -- Зробити дозволи SDK, передавання секретів, схвалення, sandboxing і віддалені - середовища явними. +- Зробити SDK permissions, secret forwarding, approvals, sandboxing і remote + environments явними. - Зберегти публічний контракт достатньо малим, щоб його можна було документувати, тестувати, версіонувати та генерувати. ## Нецілі -- Не відкривати `openclaw/plugin-sdk/*` як SDK застосунків. -- Не робити ACP єдиною моделлю середовища виконання. -- Не вимагати хмарного сервісу до того, як SDK стане корисним. +- Не відкривати `openclaw/plugin-sdk/*` як app SDK. +- Не робити ACP єдиною runtime model. +- Не вимагати cloud service до того, як SDK стане корисним. - Не клонувати API Cursor, Claude, OpenAI, ADK, OpenCode, Codex або ACP - буквально. -- Не відкривати необмежені payloads подій `any` як єдиний публічний контракт. -- Не обіцяти ізоляцію sandbox або мережеву ізоляцію для зовнішнього harness, якщо - вибране середовище не може фактично її забезпечити. -- Не змушувати авторів Plugin залежати від об’єктів SDK застосунків усередині коду - середовища виконання Plugin. + дослівно. +- Не виставляти необмежені payloads подій `any` як єдиний публічний контракт. +- Не обіцяти sandbox або network isolation для external harness, якщо + вибране середовище не може реально це забезпечити. +- Не змушувати авторів plugin залежати від об’єктів app SDK всередині runtime + code plugin. ## Поточна відповідність OpenClaw -OpenClaw уже має більшу частину основи: +OpenClaw уже має більшість основи: -| Наявна поверхня | Що вона дає | +| Наявна surface | Що вона дає | | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | -| [Цикл агента](/uk/concepts/agent-loop) | Життєвий цикл запуску `agent` і `agent.wait`, потокова передача, тайм-аут і серіалізація сесії. | -| [Середовища виконання агентів](/uk/concepts/agent-runtimes) | Розділення провайдера, моделі, середовища виконання та каналу. | -| [Агенти ACP](/uk/tools/acp-agents) | Сесії зовнішніх harnesses для Claude Code, Cursor, Gemini CLI, OpenCode, явного Codex ACP та подібних інструментів. | -| [Фонові завдання](/uk/automation/tasks) | Відокремлений журнал активності для ACP, субагентів, Cron, операцій CLI та асинхронних медіазавдань. | -| [Субагенти](/uk/tools/subagents) | Ізольовані фонові запуски агентів, необов’язковий forked context, доставлення назад у сесії запитувача. | -| [Plugins harness агентів](/uk/plugins/sdk-agent-harness) | Реєстрація довіреного нативного середовища виконання для вбудованих harnesses, таких як Codex. | -| Схеми протоколу Gateway | Поточні типізовані визначення методів і подій для параметрів агентів, сесій, підписок, переривань, Compaction і контрольних точок. | +| [Agent loop](/uk/concepts/agent-loop) | Життєвий цикл запуску `agent` і `agent.wait`, streaming, timeout і session serialization. | +| [Agent runtimes](/uk/concepts/agent-runtimes) | Розділення provider, model, runtime і channel. | +| [ACP agents](/uk/tools/acp-agents) | Sessions зовнішнього harness для Claude Code, Cursor, Gemini CLI, OpenCode, explicit Codex ACP і подібних інструментів. | +| [Background tasks](/uk/automation/tasks) | Відокремлений ledger активності для ACP, subagents, Cron, CLI operations і async media jobs. | +| [Sub-agents](/uk/tools/subagents) | Ізольовані фонові agent runs, optional forked context, доставка назад у requester sessions. | +| [Agent harness plugins](/uk/plugins/sdk-agent-harness) | Реєстрація trusted native runtime для embedded harnesses, таких як Codex. | +| Gateway protocol schemas | Поточні типізовані визначення method і event для agent params, sessions, subscriptions, aborts, Compaction і checkpoints. | -Прогалина не в запуску агентів. Прогалина в стабільному, зручному публічному фасаді поверх -цих частин. +Прогалина не в agent execution. Прогалина — у стабільному, зручному публічному facade над +цими компонентами. -## Базова модель +## Основна модель -SDK застосунків має використовувати невеликий набір стійких іменників. +App SDK має використовувати невеликий набір стійких іменників. | Іменник | Значення | | ------------- | -------------------------------------------------------------------------------------------------------------------------- | -| `OpenClaw` | Точка входу клієнта. Володіє виявленням Gateway, автентифікацією, низькорівневим доступом клієнта та фабриками просторів імен. | -| `Agent` | Налаштований актор. Містить id агента, модель за замовчуванням, середовище виконання за замовчуванням, політику інструментів за замовчуванням і помічники для застосунків. | -| `Session` | Стійкий транскрипт, маршрутизація, робочий простір, контекст і прив’язка середовища виконання. | -| `Run` | Один надісланий хід або завдання. Потоково передає події, очікує на результат, скасовує та відкриває артефакти. | -| `Task` | Запис у журналі відокремленої або фонової активності. Охоплює субагентів, породження ACP, завдання Cron, запуски CLI та асинхронні завдання. | -| `Artifact` | Файли, патчі, diff-и, медіа, журнали, траєкторії, pull requests, знімки екрана та згенеровані bundles. | -| `Environment` | Де виконується запуск: локальний Gateway, локальний робочий простір, хост node, ACP harness, керований runner або майбутній хмарний робочий простір. | -| `ToolSpace` | Ефективна поверхня інструментів: інструменти OpenClaw, сервери MCP, інструменти каналів, інструменти застосунків, правила схвалення та метадані інструментів. | -| `Approval` | Рішення людини або політики, запитане запуском, інструментом, середовищем або harness. | +| `OpenClaw` | Точка входу клієнта. Володіє Gateway discovery, auth, low-level client access і namespace factories. | +| `Agent` | Налаштований actor. Містить agent id, default model, default runtime, default tool policy і app-facing helpers. | +| `Session` | Стійкий transcript, routing, workspace, context і runtime binding. | +| `Run` | Один надісланий turn або task. Streams events, waits for result, cancels і exposes artifacts. | +| `Task` | Detached або background activity ledger entry. Охоплює subagents, ACP spawns, Cron jobs, CLI runs і async jobs. | +| `Artifact` | Files, patches, diffs, media, logs, trajectories, pull requests, screenshots і generated bundles. | +| `Environment` | Де виконується run: local Gateway, local workspace, node host, ACP harness, managed runner або майбутній cloud workspace. | +| `ToolSpace` | Ефективна tool surface: OpenClaw tools, MCP servers, channel tools, app tools, approval rules і tool metadata. | +| `Approval` | Рішення людини або політики, запитане run, tool, environment або harness. | -Ці іменники чисто відображаються на наявні концепції OpenClaw, але не розкривають -назви, специфічні для реалізації, такі як внутрішні деталі PI runner, реєстрація Plugin harness -або деталі адаптера ACP. +Ці іменники добре мапляться на наявні концепції OpenClaw, але не розкривають +implementation-specific names, такі як внутрішні механізми PI runner, реєстрація plugin harness +або деталі ACP adapter. ## Форма продукту -Високорівневий SDK має виглядати так: +Високорівневий SDK має відчуватися так: ```typescript import { OpenClaw } from "@openclaw/sdk"; @@ -136,7 +143,7 @@ const result = await run.wait(); console.log(result.status); ``` -Той самий застосунок має вміти використовувати стійкий сеанс: +Той самий застосунок має мати змогу використовувати durable session: ```typescript const session = await oc.sessions.create({ @@ -148,9 +155,16 @@ const run = await session.send("Prepare release notes from the current diff."); await run.wait(); ``` -Примітка щодо поточної реалізації: `@openclaw/sdk` починає з поверхні, підтримуваної Gateway, яка існує сьогодні. Посилання на моделі з уточненням провайдера, як-от `openai/gpt-5.5`, розділяються на перевизначення Gateway `provider` і `model`. Вибір `workspace`, `runtime`, `environment` і `approvals` для окремого запуску все ще є цільовим дизайном; клієнт викидає помилку, коли викликачі задають їх, щоб запити не виконувалися мовчки зі значеннями за замовчуванням. Допоміжні засоби для завдань, артефактів, середовищ і загального виклику інструментів також заготовлені як майбутня форма API та викидають явні помилки про непідтримуваність, доки для них не з’являться Gateway RPC. +Поточна примітка щодо реалізації: `@openclaw/sdk` починається з Gateway-backed +surface, яка існує сьогодні. Provider-qualified model refs, такі як +`openai/gpt-5.5`, розділяються на Gateway `provider` і `model` overrides. +Per-run вибори `workspace`, `runtime`, `environment` і `approvals` усе ще є +дизайнерськими цілями; клієнт кидає помилку, коли callers задають їх, щоб requests не +виконувалися мовчки з defaults. Task, artifact, environment і generic tool +invocation helpers також scaffolded як майбутня форма API і кидають явні +unsupported errors, доки для них не існує Gateway RPCs. -І той самий API має вміти використовувати зовнішній ACP harness: +І той самий API має мати змогу використовувати зовнішній ACP harness: ```typescript const run = await oc.runs.create({ @@ -161,7 +175,7 @@ const run = await oc.runs.create({ }); ``` -Керовані середовища не мають змінювати API верхнього рівня: +Managed environments не мають змінювати top-level API: ```typescript const run = await agent.run({ @@ -175,9 +189,9 @@ const run = await agent.run({ }); ``` -## Вибір середовища виконання +## Вибір runtime -SDK застосунку має надавати вибір середовища виконання як нормалізоване об’єднання: +App SDK має надавати вибір runtime як normalized union: ```typescript type RuntimeSelection = @@ -190,17 +204,22 @@ type RuntimeSelection = Правила: -- `auto` дотримується правил вибору середовища виконання OpenClaw. -- `embedded` націлюється на довірені внутрішньопроцесні harnesses, зареєстровані через plugin SDK, як-от `pi` або `codex`. -- `cli` націлюється на виконання через CLI backend, що належить OpenClaw, де це доступно. +- `auto` дотримується правил вибору runtime OpenClaw. +- `embedded` націлюється на trusted in-process harnesses, зареєстровані через plugin + SDK, такі як `pi` або `codex`. +- `cli` націлюється на OpenClaw-owned CLI backend execution там, де вона доступна. - `acp` націлюється на зовнішні harnesses через ACP/acpx. -- `managed` націлюється на провайдера середовища й усе ще може запускати embedded, CLI або ACP runtime всередині цього середовища. +- `managed` націлюється на environment provider і все ще може запускати embedded, + CLI або ACP runtime всередині цього environment. -Об’єкт вибору середовища виконання має бути описовим. Це не має бути місцем, де приховуються обробка секретів, політика пісочниці або підготовка робочого простору. +Об’єкт вибору runtime має бути описовим. Він не має бути місцем, +де ховаються secret handling, sandbox policy або workspace provisioning. -## Модель середовища +## Модель environment -Середовище є субстратом виконання. Воно має бути явним, оскільки локальні CLI-запуски, зовнішні harnesses, хости node і хмарні робочі простори мають різні властивості безпеки та життєвого циклу. +Environment — це execution substrate. Він має бути явним, оскільки локальні +CLI runs, external harnesses, node hosts і cloud workspaces мають різні +властивості безпеки та життєвого циклу. ```typescript type EnvironmentSelection = @@ -211,40 +230,43 @@ type EnvironmentSelection = | { type: "ephemeral"; provider: string; repo?: string; ref?: string }; ``` -Середовище відповідає за: +Environment володіє: -- підготовку checkout або робочого простору -- доступ до процесів і файлів -- застосування пісочниці та мережевих обмежень -- змінні середовища та посилання на секрети -- журнали, трасування й артефакти -- очищення та зберігання -- доступність середовища виконання +- підготовкою checkout або workspace +- доступом до процесів і файлів +- забезпеченням sandbox і network +- environment variables і secret references +- logs, traces і artifacts +- cleanup і retention +- availability runtime -Такий поділ робить керованих агентів природним розширенням SDK. Керований агент — це звичайний запуск у керованому середовищі, а не спеціальне відгалуження продукту. +Це розділення робить managed agents природним розширенням SDK. Managed +agent — це звичайний run у managed environment, а не окреме продуктове відгалуження. -Докладні контракти простору імен, подій, результатів, схвалень, артефактів, безпеки, пакетів і провайдерів середовищ містяться в [дизайні OpenClaw SDK API](/uk/reference/openclaw-sdk-api-design). +Детальні контракти namespace, event, result, approval, artifact, security, package, +і environment provider містяться в +[OpenClaw App SDK API design](/uk/reference/openclaw-sdk-api-design). -## План збірника рецептів +## План cookbook -SDK має постачатися зі збірником рецептів, а не лише з довідковою документацією. +SDK має постачатися з кулінарною книгою, а не лише з довідковою документацією. Рекомендовані приклади: | Приклад | Показує | | ---------------------------- | -------------------------------------------------------------------------------------------- | | Швидкий старт | Створення клієнта, запуск агента, потокове виведення, очікування результату. | -| CLI кодингового агента | Локальний робочий простір, вибір моделі, скасування, затвердження, JSON-вивід. | -| Панель агента | Сесії, запуски, фонові завдання, артефакти, повторне відтворення подій, фільтри статусу. | +| CLI кодувального агента | Локальний робочий простір, вибір моделі, скасування, схвалення, JSON-вивід. | +| Панель агента | Сесії, запуски, фонові завдання, артефакти, відтворення подій, фільтри статусу. | | Конструктор застосунків | Агент редагує робочий простір, поки поруч працює сервер попереднього перегляду. | -| Рецензент pull request | Запуск для посилання на репозиторій, збирання коментарів до diff і артефактів. | -| Консоль затверджень | Підписка на затвердження й відповіді на них з UI. | -| Запускач ACP harness | Запуск Claude Code, Cursor, Gemini CLI або OpenCode через ACP з використанням того самого API `Run`. | -| Провайдер керованого середовища | Мінімальний провайдер, який готує робочий простір, транслює події, зберігає артефакти та очищає ресурси. | -| Міст Slack або Discord | Зовнішній застосунок отримує події та публікує підсумки прогресу, не стаючи Plugin каналу. | +| Рецензент pull request | Запуск для посилання репозиторію, збирання коментарів до diff і артефактів. | +| Консоль схвалень | Підписка на схвалення та відповіді на них з UI. | +| Запускач ACP harness | Запуск Claude Code, Cursor, Gemini CLI або OpenCode через ACP за допомогою того самого API `Run`. | +| Постачальник керованого середовища | Мінімальний постачальник, який готує робочий простір, транслює події, зберігає артефакти та очищує ресурси. | +| Міст Slack або Discord | Зовнішній застосунок отримує події та публікує зведення прогресу, не стаючи Plugin каналу. | | Багатоагентне дослідження | Породження паралельних запусків, збирання артефактів і синтез фінального звіту. | -Приклади cookbook мають спершу використовувати високорівневий API. Приклади низькорівневого згенерованого +Приклади кулінарної книги мають спершу використовувати високорівневий API. Приклади низькорівневого згенерованого клієнта належать до розширеного розділу. ## Поетапна реалізація @@ -254,105 +276,106 @@ SDK має постачатися зі збірником рецептів, а - Узгодити публічні іменники та назви. - Визначити назви пакетів. - Визначити першу таксономію подій. -- Позначити в документації поточний Plugin SDK як навмисно окремий. +- Позначити поточний Plugin SDK у документації як навмисно окремий. ### Фаза 1: Низькорівневий згенерований клієнт - Згенерувати TypeScript-клієнт зі схем протоколу Gateway. -- Спершу охопити `agent`, `agent.wait`, сесії, підписки, переривання та завдання. -- Додати smoke-тести, які перевіряють, що згенеровані методи відповідають назвам методів Gateway і формам схем. +- Спершу покрити `agent`, `agent.wait`, сесії, підписки, переривання та завдання. +- Додати smoke-тести, які перевіряють, що згенеровані методи відповідають назвам методів Gateway і + формам схем. - Опублікувати як експериментальний або внутрішній пакет. ### Фаза 2: Високорівневий API запуску - Додати `OpenClaw`, `Agent`, `Session` і `Run`. - Підтримати `run.events()`, `run.wait()` і `run.cancel()`. -- Підтримати локальне виявлення Gateway та явні URL Gateway. +- Підтримати виявлення локального Gateway і явні URL Gateway. - Підтримати довговічні сесії та надсилання в сесію. ### Фаза 3: Нормалізована проєкція подій - Додати на боці Gateway нормалізовану проєкцію подій поруч з наявними сирими подіями. -- Зберігати сирі події середовища виконання там, де це дозволяє політика. -- Додати курсори повторного відтворення та поведінку повторного підключення. +- Зберегти сирі події середовища виконання там, де це дозволяє політика. +- Додати курсори відтворення та поведінку повторного підключення. - Відобразити події PI, Codex, ACP і завдань у стабільну таксономію. -### Фаза 4: Артефакти та затвердження +### Фаза 4: Артефакти та схвалення - Додати перелік і завантаження артефактів. -- Додати підписку на затвердження та помічники для відповідей. -- Додати підписку на запитання та помічники для відповідей. -- Додати cookbook-консоль затверджень. +- Додати помічники підписки на схвалення та відповіді. +- Додати помічники підписки на запитання та відповіді. +- Додати консоль схвалень до кулінарної книги. -### Фаза 5: Провайдери середовищ +### Фаза 5: Постачальники середовищ -- Запровадити контракти локального, node- і керованого провайдерів середовищ. -- Почати із середовища, яке вже існує операційно. -- Додати підготовку робочого простору, журнали, артефакти, timeout, очищення та утримання. +- Запровадити контракти постачальників локального, вузлового та керованого середовища. +- Почати з середовища, яке вже існує операційно. +- Додати підготовку робочого простору, журнали, артефакти, тайм-аут, очищення та зберігання. -### Фаза 6: Робочі процеси у хмарному стилі +### Фаза 6: Робочі процеси в хмарному стилі - Додати запуски, орієнтовані на репозиторій і гілку. - Додати артефакти pull request. - Додати дошки запусків, згруповані за репозиторієм, гілкою, статусом і виконавцем. -- Додати довготривалі керовані сесії та політику утримання. +- Додати довготривалі керовані сесії та політику зберігання. -## Проєктні рішення для наслідування +## Дизайн-рішення для наслідування Скопіювати ці ідеї: -- З Cursor: `Agent` плюс `Run`, симетрія локального й хмарного режимів, виявлення моделей, - артефакти та онбординг на основі cookbook. -- З Claude Agent SDK: двонапрямні клієнти, interrupt, permissions, hooks, - custom tools, сховища сесій і семантика resume. -- З OpenAI Agents: handoffs, guardrails, відновлення після затвердження людиною, трасування та +- З Cursor: `Agent` плюс `Run`, симетрія локального та хмарного режимів, виявлення моделей, + артефакти й onboarding через кулінарну книгу. +- З Claude Agent SDK: двонапрямні клієнти, переривання, дозволи, hooks, + користувацькі інструменти, сховища сесій і семантика відновлення. +- З OpenAI Agents: передавання керування, захисні обмеження, відновлення після людського схвалення, трасування та структуровані об’єкти потокового результату. - З Google ADK: сервіси за runner, дії подій, пам’ять, артефакти, - сервіси облікових даних і Plugin-перехоплення навколо життєвого циклу запуску. + сервіси облікових даних і перехоплення Plugin навколо життєвого циклу запуску. - З OpenCode: згенерований клієнт протоколу, REST плюс SSE, сесії, - робочі простори, запитання, дозволи, файли, VCS, PTY, MCP, агенти та skills. -- З Codex: явні sandbox, approval, network, локальне й віддалене виконання, а також + робочі простори, запитання, дозволи, файли, VCS, PTY, MCP, агенти та Skills. +- З Codex: явні пісочниця, схвалення, мережа, локальне та віддалене виконання, а також межі потоків app-server. - З ACP і acpx: сумісність зовнішніх harness на основі адаптерів і іменовані черги prompt. -## Проєктні рішення, яких слід уникати +## Дизайн-рішення, яких слід уникати Уникайте цих пасток: - Публічний SDK, який є лише тонким вивантаженням внутрішніх деталей Gateway. - Публічний SDK, який імпортує підшляхи Plugin SDK. -- Публічний SDK, де події є лише `stream` плюс `data`. -- API, орієнтований насамперед на хмару, через який локальний OpenClaw відчувається як застарілий режим. -- Вибір середовища виконання, прихований у префіксах id моделей. +- Публічний SDK, де події — це лише `stream` плюс `data`. +- API з пріоритетом хмари, через який локальний OpenClaw відчувається як застарілий режим. +- Вибір середовища виконання, прихований у префіксах ідентифікаторів моделей. - Передавання секретів, приховане в мапах середовища. - ACP-специфічні параметри на верхньому рівні кожного запуску. -- Прапорці sandbox, які неможливо забезпечити вибраним середовищем виконання. -- Один об’єкт SDK, який одночасно намагається бути Plugin провайдера, Plugin каналу, клієнтом застосунку +- Прапорці пісочниці, які неможливо забезпечити вибраним середовищем виконання. +- Один об’єкт SDK, який одночасно намагається бути provider Plugin, channel Plugin, клієнтом застосунку і керованим runner. ## Відкриті питання -- Початковий пакет має жити в цьому репозиторії чи в окремому SDK-репозиторії? -- Чи слід публічно опублікувати згенерований низькорівневий клієнт до того, як - стабілізується високорівнева обгортка? -- Який перший підтримуваний механізм автентифікації застосунку: локальний токен, адмін-токен, +- Чи має початковий пакет жити в цьому репозиторії чи в окремому репозиторії SDK? +- Чи слід публікувати згенерований низькорівневий клієнт публічно до стабілізації + високорівневої обгортки? +- Який перший підтримуваний механізм автентифікації застосунку: локальний токен, admin-токен, OAuth device flow чи підписана реєстрація застосунку? - Скільки історії повідомлень сесії SDK має відкривати за замовчуванням? -- Чи керовані середовища мають налаштовуватися лише в конфігурації Gateway, чи виклики SDK +- Чи мають керовані середовища налаштовуватися лише в конфігурації Gateway, чи виклики SDK можуть запитувати їх напряму зі scoped tokens? -- Які правила утримання застосовуються до артефактів, згенерованих локальними запусками? +- Які правила зберігання застосовуються до артефактів, згенерованих локальними запусками? - Які payload подій потребують редагування перед доставленням у застосунок? -- Чи має `Run` охоплювати звичайні чат-ходи й відокремлені завдання, чи відокремлена +- Чи має `Run` покривати звичайні ходи чату й відокремлені завдання, чи відокремлена фонова робота завжди має повертати обгортку `Task` з вкладеним `Run`? ## Пов’язані документи - [Цикл агента](/uk/concepts/agent-loop) -- [Середовища виконання агентів](/uk/concepts/agent-runtimes) +- [Середовища виконання агента](/uk/concepts/agent-runtimes) - [Сесія](/uk/concepts/session) - [Субагенти](/uk/tools/subagents) - [Фонові завдання](/uk/automation/tasks) -- [ACP-агенти](/uk/tools/acp-agents) -- [Plugins agent harness](/uk/plugins/sdk-agent-harness) +- [Агенти ACP](/uk/tools/acp-agents) +- [Agent harness plugins](/uk/plugins/sdk-agent-harness) - [Огляд Plugin SDK](/uk/plugins/sdk-overview) diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index a4cd41530..fcbb9ecb4 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,27 +1,35 @@ --- read_when: - - Потрібно знати, з якого підшляху SDK виконувати імпорт + - Потрібно знати, з якого підшляху SDK імпортувати - Вам потрібна довідка щодо всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK -sidebarTitle: SDK overview -summary: Карта імпортів, довідник API реєстрації та архітектура SDK +sidebarTitle: Plugin SDK overview +summary: Мапа імпортів, довідник API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-29T04:42:21Z" + generated_at: "2026-04-30T00:49:45Z" model: gpt-5.5 provider: openai - source_hash: 7652c2be756dad14792f59f36fa2fc2becd1681454005cf391e401b89999b857 + source_hash: 1749ad99c55ffd14624b817aba963bd93ebe7976937138693177523bbe3aa88c source_path: plugins/sdk-overview.md workflow: 16 --- -SDK Plugin є типізованим контрактом між плагінами та ядром. Ця сторінка є довідником щодо того, **що імпортувати** і **що можна реєструвати**. +Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка є +довідником щодо **того, що імпортувати** і **що можна реєструвати**. + + + Ця сторінка призначена для авторів plugins, які використовують `openclaw/plugin-sdk/*` всередині + OpenClaw. Для зовнішніх застосунків, скриптів, панелей керування, завдань CI та розширень IDE, + які хочуть запускати агентів через Gateway, натомість використовуйте + [OpenClaw App SDK](/uk/concepts/openclaw-sdk) і пакет `@openclaw/sdk`. + -Шукаєте натомість практичний посібник? Почніть із [Створення плагінів](/uk/plugins/building-plugins), використовуйте [Плагіни каналів](/uk/plugins/sdk-channel-plugins) для плагінів каналів, [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins) для плагінів провайдерів і [Хуки Plugin](/uk/plugins/hooks) для плагінів інструментів або хуків життєвого циклу. +Шукаєте натомість практичний посібник? Почніть із [Створення plugins](/uk/plugins/building-plugins), використовуйте [Channel plugins](/uk/plugins/sdk-channel-plugins) для channel plugins, [Provider plugins](/uk/plugins/sdk-provider-plugins) для provider plugins і [Plugin hooks](/uk/plugins/hooks) для plugins інструментів або хуків життєвого циклу. -## Угода про імпорт +## Угода щодо імпорту Завжди імпортуйте з конкретного підшляху: @@ -30,163 +38,166 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Кожен підшлях є невеликим самодостатнім модулем. Це забезпечує швидкий запуск і -запобігає проблемам із циклічними залежностями. Для допоміжних засобів входу/збірки, -специфічних для каналів, віддавайте перевагу `openclaw/plugin-sdk/channel-core`; залиште `openclaw/plugin-sdk/core` для -ширшої узагальнювальної поверхні та спільних допоміжних засобів, таких як +Кожен підшлях — це невеликий самодостатній модуль. Це пришвидшує запуск і +запобігає проблемам із циклічними залежностями. Для специфічних для каналів помічників entry/build +надавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для +ширшої парасолькової поверхні та спільних помічників, як-от `buildChannelConfigSchema`. Для конфігурації каналу публікуйте JSON Schema, що належить каналу, через `openclaw.plugin.json#channelConfigs`. Підшлях `plugin-sdk/channel-config-schema` -призначений для спільних примітивів схем і загального конструктора. Вбудовані -плагіни OpenClaw використовують `plugin-sdk/bundled-channel-config-schema` для збережених +призначений для спільних примітивів схем і універсального збирача. Вбудовані +plugins OpenClaw використовують `plugin-sdk/bundled-channel-config-schema` для збережених схем вбудованих каналів. Застарілі експорти сумісності залишаються в -`plugin-sdk/channel-config-schema-legacy`; жоден із підшляхів вбудованих схем не є -шаблоном для нових плагінів. +`plugin-sdk/channel-config-schema-legacy`; жоден із підшляхів схем вбудованих каналів не є +шаблоном для нових plugins. - Не імпортуйте зручні seams із брендингом провайдера або каналу (наприклад, + Не імпортуйте provider- або channel-брендовані допоміжні межі (наприклад `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). - Вбудовані плагіни компонують загальні підшляхи SDK у власних barrel-файлах `api.ts` / - `runtime-api.ts`; споживачі ядра мають або використовувати ці локальні для плагіна - barrel-файли, або додати вузький загальний контракт SDK, коли потреба справді є + Вбудовані plugins компонують універсальні підшляхи SDK всередині власних barrel-файлів `api.ts` / + `runtime-api.ts`; споживачі ядра мають або використовувати ці локальні для plugin + barrel-файли, або додавати вузький універсальний контракт SDK, коли потреба справді є міжканальною. -Невеликий набір допоміжних seams вбудованих плагінів досі з'являється у згенерованій мапі експортів, -коли для них відстежується використання власником. Вони існують лише для -супроводу вбудованих плагінів і не рекомендовані як шляхи імпорту для нових сторонніх -плагінів. +Невеликий набір допоміжних меж для вбудованих plugins усе ще з’являється у згенерованій мапі експортів, +коли вони мають відстежене використання власником. Вони існують лише для супроводу вбудованих plugins +і не рекомендовані як шляхи імпорту для нових сторонніх +plugins. `openclaw/plugin-sdk/discord` і `openclaw/plugin-sdk/telegram-account` також -збережені як застарілі фасади сумісності для відстежуваного використання власником. Не -копіюйте ці шляхи імпорту в нові плагіни; натомість використовуйте ін'єктовані runtime-допоміжні засоби та -загальні підшляхи SDK каналів. +збережені як застарілі фасади сумісності для відстеженого використання власником. Не +копіюйте ці шляхи імпорту в нові plugins; натомість використовуйте ін’єктовані runtime-помічники та +універсальні підшляхи channel SDK. ## Довідник підшляхів -SDK Plugin надається як набір вузьких підшляхів, згрупованих за областями (вхід -плагіна, канал, провайдер, автентифікація, runtime, capability, пам'ять і зарезервовані -допоміжні засоби вбудованих плагінів). Повний каталог — згрупований і з посиланнями — див. -[Підшляхи SDK Plugin](/uk/plugins/sdk-subpaths). +Plugin SDK надається як набір вузьких підшляхів, згрупованих за областями (entry plugin, +канал, provider, автентифікація, runtime, capability, пам’ять і зарезервовані +помічники вбудованих plugins). Повний каталог — згрупований і з посиланнями — див. +[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths). -Згенерований список із понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`. +Згенерований список із понад 200 підшляхів розміщений у `scripts/lib/plugin-sdk-entrypoints.json`. ## API реєстрації -Callback `register(api)` отримує об'єкт `OpenClawPluginApi` з такими +Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: -### Реєстрація capability +### Реєстрація capabilities -| Метод | Що він реєструє | -| ------------------------------------------------ | -------------------------------------- | -| `api.registerProvider(...)` | Текстове виведення (LLM) | -| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | -| `api.registerCliBackend(...)` | Локальний backend виведення CLI | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| Метод | Що реєструє | +| ------------------------------------------------ | ------------------------------------- | +| `api.registerProvider(...)` | Текстовий inference (LLM) | +| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агентів | +| `api.registerCliBackend(...)` | Локальний backend inference для CLI | +| `api.registerChannel(...)` | Канал повідомлень | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | | `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер веботримання / скрейпінгу | -| `api.registerWebSearchProvider(...)` | Вебпошук | +| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сеанси в реальному часі | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerMusicGenerationProvider(...)` | Генерація музики | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Provider web fetch / scrape | +| `api.registerWebSearchProvider(...)` | Вебпошук | -### Інструменти та команди +### Інструменти й команди -| Метод | Що він реєструє | -| ------------------------------- | ------------------------------------------------ | -| `api.registerTool(tool, opts?)` | Інструмент агента (обов'язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | +| Метод | Що реєструє | +| ------------------------------- | -------------------------------------------- | +| `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | +| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | Команди Plugin можуть задавати `agentPromptGuidance`, коли агенту потрібна коротка, -належна команді підказка маршрутизації. Тримайте цей текст про саму команду; не додавайте -політику, специфічну для провайдера або плагіна, до конструкторів core prompt. +належна команді підказка для маршрутизації. Тримайте цей текст про саму команду; не додавайте +provider- або plugin-специфічну політику до збирачів prompt ядра. ### Інфраструктура -| Метод | Що він реєструє | -| ---------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Хук події | -| `api.registerHttpRoute(params)` | HTTP endpoint Gateway | -| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | -| `api.registerGatewayDiscoveryService(service)` | Оголошувач локального виявлення Gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фоновий сервіс | -| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | -| `api.registerAgentToolResultMiddleware(...)` | Runtime middleware результатів інструментів | -| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ prompt поруч із пам'яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам'яті | +| Метод | Що реєструє | +| ---------------------------------------------- | -------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Хук події | +| `api.registerHttpRoute(params)` | HTTP endpoint Gateway | +| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | +| `api.registerGatewayDiscoveryService(service)` | Рекламодавець виявлення локального Gateway | +| `api.registerCli(registrar, opts?)` | Підкоманда CLI | +| `api.registerService(service)` | Фоновий сервіс | +| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | +| `api.registerAgentToolResultMiddleware(...)` | Runtime middleware для результатів інструментів | +| `api.registerMemoryPromptSupplement(builder)` | Адитивна секція prompt поруч із пам’яттю | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | -### Хост-хуки для плагінів workflow +### Host hooks для workflow plugins -Хост-хуки — це seams SDK для плагінів, яким потрібно брати участь у життєвому циклі хоста, -а не лише додавати провайдера, канал або інструмент. Вони є -загальними контрактами; Plan Mode може їх використовувати, але так само можуть workflow затверджень, -гейти політик робочого простору, фонові монітори, майстри налаштування та супровідні UI -плагіни. +Host hooks — це межі SDK для plugins, яким потрібно брати участь у життєвому циклі хоста, +а не лише додавати provider, канал або інструмент. Це +універсальні контракти; Plan Mode може їх використовувати, але так само можуть workflow-и погодження, +шлюзи політик робочого простору, фонові монітори, майстри налаштування та UI companion +plugins. -| Метод | Контракт, яким він володіє | -| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | -| `api.registerSessionExtension(...)` | Належний Plugin JSON-сумісний стан сесії, проєктований через сесії Gateway | -| `api.enqueueNextTurnInjection(...)` | Стійкий контекст exactly-once, ін'єктований у наступний хід агента для однієї сесії | -| `api.registerTrustedToolPolicy(...)` | Політика інструментів до Plugin для вбудованих/довірених інструментів, що може блокувати або переписувати параметри інструмента | -| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента | -| `api.registerCommand(...)` | Обмежені за scope команди Plugin; результати команд можуть задавати `continueAgent: true` | -| `api.registerControlUiDescriptor(...)` | Дескриптори внеску Control UI для поверхонь сесії, інструмента, запуску або налаштувань | -| `api.registerRuntimeLifecycle(...)` | Callback-и очищення для належних Plugin runtime-ресурсів на шляхах reset/delete/reload | -| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану workflow та моніторів | -| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Належний Plugin scratch-стан для кожного запуску, очищений у термінальному життєвому циклі запуску | -| `api.registerSessionSchedulerJob(...)` | Належні Plugin записи завдань планувальника сесій із детермінованим очищенням | +| Метод | Контракт, яким він володіє | +| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------- | +| `api.registerSessionExtension(...)` | Належний plugin JSON-сумісний стан сеансу, спроєктований через сеанси Gateway | +| `api.enqueueNextTurnInjection(...)` | Надійний exactly-once контекст, ін’єктований у наступний хід агента для одного сеансу | +| `api.registerTrustedToolPolicy(...)` | Політика інструментів перед bundled/trusted pre-plugin, яка може блокувати або переписувати параметри інструментів | +| `api.registerToolMetadata(...)` | Метадані відображення каталогу інструментів без зміни реалізації інструмента | +| `api.registerCommand(...)` | Scoped команди plugin; результати команд можуть задавати `continueAgent: true` | +| `api.registerControlUiDescriptor(...)` | Дескриптори внеску Control UI для поверхонь сеансу, інструмента, запуску або налаштувань | +| `api.registerRuntimeLifecycle(...)` | Зворотні виклики очищення для runtime-ресурсів, що належать plugin, на шляхах reset/delete/reload | +| `api.registerAgentEventSubscription(...)` | Санітизовані підписки на події для стану workflow і моніторів | +| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | Scratch-стан plugin для кожного запуску, очищений на термінальному життєвому циклі запуску | +| `api.registerSessionSchedulerJob(...)` | Належні plugin записи завдань планувальника сеансів із детермінованим очищенням | Контракти навмисно розділяють повноваження: -- Зовнішні плагіни можуть володіти розширеннями сесій, UI-дескрипторами, командами, метаданими інструментів, ін'єкціями наступного ходу та звичайними хуками. -- Довірені політики інструментів виконуються перед звичайними хуками `before_tool_call` і доступні лише для вбудованих компонентів, бо беруть участь у політиці безпеки хоста. -- Зарезервоване володіння командами доступне лише для вбудованих компонентів. Зовнішні плагіни мають використовувати власні назви команд або псевдоніми. -- `allowPromptInjection=false` вимикає хуки, що змінюють prompt, включно з +- Зовнішні plugins можуть володіти session extensions, UI descriptors, commands, tool + metadata, next-turn injections і звичайними hooks. +- Trusted tool policies виконуються перед звичайними hooks `before_tool_call` і є + лише вбудованими, бо вони беруть участь у політиці безпеки хоста. +- Зарезервоване володіння командами доступне лише вбудованим plugins. Зовнішні plugins мають використовувати + власні імена команд або псевдоніми. +- `allowPromptInjection=false` вимикає hooks, що змінюють prompt, зокрема `agent_turn_prepare`, `before_prompt_build`, `heartbeat_prompt_contribution`, - полями prompt із застарілого `before_agent_start` і + поля prompt із legacy `before_agent_start` і `enqueueNextTurnInjection`. Приклади споживачів, що не належать до Plan: -| Архетип Plugin | Використані хуки | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| Workflow затвердження | Розширення сесії, продовження команди, ін'єкція наступного ходу, UI-дескриптор | -| Гейт політики бюджету/робочого простору | Довірена політика інструментів, метадані інструментів, проєкція сесії | -| Фоновий монітор життєвого циклу | Очищення runtime-життєвого циклу, підписка на події агента, володіння/очищення планувальника сесій, внесок Heartbeat prompt, UI-дескриптор | -| Майстер налаштування або onboarding | Розширення сесії, обмежені за scope команди, дескриптор Control UI | +| Архетип plugin | Використані hooks | +| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Workflow погодження | Session extension, command continuation, next-turn injection, UI descriptor | +| Шлюз політик бюджету/робочого простору | Trusted tool policy, tool metadata, session projection | +| Фоновий монітор життєвого циклу | Runtime lifecycle cleanup, agent event subscription, session scheduler ownership/cleanup, heartbeat prompt contribution, UI descriptor | +| Майстер налаштування або onboarding | Session extension, scoped commands, Control UI descriptor | Зарезервовані core admin namespaces (`config.*`, `exec.approvals.*`, `wizard.*`, - `update.*`) завжди залишаються `operator.admin`, навіть якщо Plugin намагається призначити - вужчий scope методу gateway. Віддавайте перевагу префіксам, специфічним для Plugin, для - методів, якими володіє Plugin. + `update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити + вужчу область gateway method. Надавайте перевагу plugin-specific prefixes для + методів, що належать plugin. - Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли + Вбудовані plugins можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм потрібно переписати результат інструмента після виконання і до того, як runtime - передасть цей результат назад у модель. Це довірений runtime-нейтральний - seam для асинхронних редукторів виводу, таких як tokenjuice. + передасть цей результат назад у модель. Це trusted runtime-neutral + межа для async output reducers, таких як tokenjuice. -Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного -цільового runtime, наприклад `["pi", "codex"]`. Зовнішні плагіни -не можуть реєструвати це middleware; залишайте звичайні хуки Plugin OpenClaw для роботи, -яка не потребує timing результату інструмента до моделі. Старий вбудований -шлях реєстрації фабрики розширення лише для Pi було видалено. +Вбудовані plugins мають оголошувати `contracts.agentToolResultMiddleware` для кожного +цільового runtime, наприклад `["pi", "codex"]`. Зовнішні plugins +не можуть реєструвати це middleware; залишайте звичайні hooks OpenClaw plugin для роботи, +якій не потрібен таймінг результату інструмента перед моделлю. Старий Pi-only embedded +шлях реєстрації extension factory було вилучено. ### Реєстрація виявлення Gateway -`api.registerGatewayDiscoveryService(...)` дає Plugin змогу оголошувати активний -Gateway на локальному транспорті виявлення, наприклад mDNS/Bonjour. OpenClaw викликає -сервіс під час запуску Gateway, коли локальне виявлення увімкнене, передає -поточні порти Gateway і несекретні TXT hint-дані, а також викликає повернений +`api.registerGatewayDiscoveryService(...)` дає plugin змогу рекламувати активний +Gateway у локальному транспорті виявлення, як-от mDNS/Bonjour. OpenClaw викликає +сервіс під час запуску Gateway, коли локальне виявлення ввімкнено, передає +поточні порти Gateway і несекретні TXT hint-дані та викликає повернений обробник `stop` під час завершення роботи Gateway. ```typescript @@ -203,19 +214,19 @@ api.registerGatewayDiscoveryService({ }); ``` -Плагіни виявлення Gateway не повинні трактувати оголошені TXT-значення як секрети або -автентифікацію. Виявлення є routing hint; автентифікація Gateway і TLS pinning і далі +Плагіни виявлення Gateway не повинні розглядати оголошені значення TXT як секрети або +автентифікацію. Виявлення є підказкою для маршрутизації; автентифікація Gateway і прив’язка TLS і далі відповідають за довіру. ### Метадані реєстрації CLI -`api.registerCli(registrar, opts?)` приймає два види метаданих верхнього рівня: +`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: - `commands`: явні корені команд, якими володіє реєстратор -- `descriptors`: дескриптори команд часу розбору, які використовуються для довідки кореневого CLI, - маршрутизації та лінивої реєстрації CLI Plugin +- `descriptors`: дескриптори команд часу розбору, що використовуються для довідки кореневого CLI, + маршрутизації та лінивої реєстрації CLI плагіна -Якщо ви хочете, щоб команда Plugin залишалася ліниво завантажуваною у звичайному кореневому шляху CLI, +Якщо ви хочете, щоб команда плагіна залишалася ліниво завантажуваною у звичайному шляху кореневого CLI, надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, відкритий цим реєстратором. @@ -229,7 +240,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Manage Matrix accounts, verification, devices, and profile state", + description: "Керування обліковими записами Matrix, перевіркою, пристроями та станом профілю", hasSubcommands: true, }, ], @@ -237,53 +248,53 @@ api.registerCli( ); ``` -Використовуйте `commands` окремо лише тоді, коли вам не потрібна лінива реєстрація кореневого CLI. -Цей енергійний шлях сумісності й надалі підтримується, але він не встановлює +Використовуйте лише `commands`, тільки коли вам не потрібна лінива реєстрація кореневого CLI. +Цей шлях енергійної сумісності й надалі підтримується, але він не встановлює заповнювачі на основі дескрипторів для лінивого завантаження під час розбору. ### Реєстрація бекенду CLI -`api.registerCliBackend(...)` дає Plugin змогу володіти типовою конфігурацією для локального -бекенду AI CLI, такого як `codex-cli`. +`api.registerCliBackend(...)` дає плагіну змогу володіти типовою конфігурацією для локального +бекенду AI CLI, як-от `codex-cli`. -- `id` бекенду стає префіксом провайдера в посиланнях на моделі на кшталт `codex-cli/gpt-5`. +- `id` бекенду стає префіксом провайдера в посиланнях на моделі, як-от `codex-cli/gpt-5`. - `config` бекенду використовує ту саму форму, що й `agents.defaults.cliBackends.`. - Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх - типових налаштувань Plugin перед запуском CLI. + типових значень плагіна перед запуском CLI. - Використовуйте `normalizeConfig`, коли бекенду потрібні переписування для сумісності після об’єднання (наприклад, нормалізація старих форм прапорців). ### Ексклюзивні слоти -| Метод | Що він реєструє | -| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `api.registerContextEngine(id, factory)` | Контекстний рушій (одночасно активний лише один). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати доповнення до промпта. | -| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті | -| `api.registerMemoryPromptSection(builder)` | Побудовник секції промпта пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер середовища виконання пам’яті | +| Метод | Що він реєструє | +| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `api.registerContextEngine(id, factory)` | Рушій контексту (один активний одночасно). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг налаштувати додавання до промпта. | +| `api.registerMemoryCapability(capability)` | Уніфікована можливість пам’яті | +| `api.registerMemoryPromptSection(builder)` | Побудовник секції промпта пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер середовища виконання пам’яті | ### Адаптери ембедингів пам’яті -| Метод | Що він реєструє | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер ембедингів пам’яті для активного Plugin | +| Метод | Що він реєструє | +| ---------------------------------------------- | ---------------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер ембедингів пам’яті для активного плагіна | -- `registerMemoryCapability` — рекомендований ексклюзивний API Plugin пам’яті. -- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`, - щоб супровідні Plugins могли споживати експортовані артефакти пам’яті через - `openclaw/plugin-sdk/memory-host-core`, а не звертатися до приватної структури - конкретного Plugin пам’яті. +- `registerMemoryCapability` є бажаним ексклюзивним API плагіна пам’яті. +- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`, + щоб супутні плагіни могли споживати експортовані артефакти пам’яті через + `openclaw/plugin-sdk/memory-host-core` замість доступу до приватної структури + конкретного плагіна пам’яті. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — це сумісні зі спадщиною ексклюзивні API Plugin пам’яті. -- `MemoryFlushPlan.model` може прив’язати хід скидання до точного посилання - `provider/model`, такого як `ollama/qwen3:8b`, без успадкування активного - ланцюжка резервних варіантів. -- `registerMemoryEmbeddingProvider` дає активному Plugin пам’яті змогу зареєструвати один - або кілька ідентифікаторів адаптерів ембедингів (наприклад, `openai`, `gemini` або власний - ідентифікатор, визначений Plugin). -- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, розв’язується відносно цих зареєстрованих + `registerMemoryRuntime` є ексклюзивними API плагіна пам’яті зі збереженням сумісності зі спадщиною. +- `MemoryFlushPlan.model` може закріпити хід скидання за точним посиланням + `provider/model`, як-от `ollama/qwen3:8b`, без успадкування активного ланцюга + резервних варіантів. +- `registerMemoryEmbeddingProvider` дає активному плагіну пам’яті змогу зареєструвати один + або кілька ідентифікаторів адаптерів ембедингів (наприклад `openai`, `gemini` або власний + ідентифікатор, визначений плагіном). +- Користувацька конфігурація, як-от `agents.defaults.memorySearch.provider` і + `agents.defaults.memorySearch.fallback`, резолвиться відносно цих зареєстрованих ідентифікаторів адаптерів. ### Події та життєвий цикл @@ -293,7 +304,8 @@ api.registerCli( | `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | | `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | -Див. [хуки Plugin](/uk/plugins/hooks) для прикладів, поширених назв хуків і семантики захисту. +Див. [хуки плагінів](/uk/plugins/hooks) для прикладів, поширених назв хуків і семантики +запобіжників. ### Семантика рішень хуків @@ -301,94 +313,94 @@ api.registerCli( - `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення. - `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. - `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як пропуск `block`), а не як перевизначення. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере dispatch на себе, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере на себе доставлення, обробники з нижчим пріоритетом і типовий шлях доставлення моделі пропускаються. - `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. - `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як пропуск `cancel`), а не як перевизначення. - `message_received`: використовуйте типізоване поле `threadId`, коли потрібна маршрутизація вхідної гілки/теми. Залишайте `metadata` для специфічних для каналу додаткових даних. -- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічного для каналу `metadata`. +- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до специфічних для каналу `metadata`. - `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, яким володіє Gateway, замість покладання на внутрішні хуки `gateway:startup`. -- `cron_changed`: спостерігайте за змінами життєвого циклу Cron, яким володіє Gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()` під час синхронізації зовнішніх планувальників пробудження, а OpenClaw залишайте джерелом істини для перевірок строків виконання та виконання. +- `cron_changed`: спостерігайте за змінами життєвого циклу cron, яким володіє gateway. Використовуйте `event.job?.state?.nextRunAtMs` і `ctx.getCron?.()`, коли синхронізуєте зовнішні планувальники пробудження, і залишайте OpenClaw джерелом істини для перевірок настання часу та виконання. ### Поля об’єкта API -| Поле | Тип | Опис | -| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Ідентифікатор Plugin | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія Plugin (необов’язково) | -| `api.description` | `string?` | Опис Plugin (необов’язково) | -| `api.source` | `string` | Шлях до джерела Plugin | -| `api.rootDir` | `string?` | Кореневий каталог Plugin (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, коли доступний) | -| `api.pluginConfig` | `Record` | Специфічна для Plugin конфігурація з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Допоміжні засоби середовища виконання](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Обмежений логер (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування перед повним входом | -| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня Plugin | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | ----------------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Ідентифікатор плагіна | +| `api.name` | `string` | Відображувана назва | +| `api.version` | `string?` | Версія плагіна (необов’язково) | +| `api.description` | `string?` | Опис плагіна (необов’язково) | +| `api.source` | `string` | Шлях до джерела плагіна | +| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний знімок середовища виконання в пам’яті, коли доступний) | +| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Помічники середовища виконання](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Логер з областю дії (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — полегшене вікно запуску/налаштування до повного входу | +| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня плагіна | -## Конвенція внутрішніх модулів +## Внутрішня домовленість щодо модулів -У межах вашого Plugin використовуйте локальні barrel-файли для внутрішніх імпортів: +У своєму плагіні використовуйте локальні barrel-файли для внутрішніх імпортів: ``` my-plugin/ - api.ts # Public exports for external consumers - runtime-api.ts # Internal-only runtime exports - index.ts # Plugin entry point - setup-entry.ts # Lightweight setup-only entry (optional) + api.ts # Публічні експорти для зовнішніх споживачів + runtime-api.ts # Внутрішні експорти середовища виконання + index.ts # Точка входу плагіна + setup-entry.ts # Полегшений вхід лише для налаштування (необов’язково) ``` - Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/` - з виробничого коду. Спрямовуйте внутрішні імпорти через `./api.ts` або - `./runtime-api.ts`. Шлях SDK — лише зовнішній контракт. + Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` + з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або + `./runtime-api.ts`. Шлях SDK є лише зовнішнім контрактом. -Публічні поверхні вбудованих Plugin, завантажені через фасад (`api.ts`, `runtime-api.ts`, +Публічні поверхні вбудованого плагіна, завантажені через фасад (`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts` і подібні публічні вхідні файли), віддають перевагу -активному знімку конфігурації середовища виконання, коли OpenClaw уже запущено. Якщо знімка середовища -виконання ще немає, вони повертаються до розв’язаної конфігурації на диску. -Фасади упакованих вбудованих Plugin слід завантажувати через фасадні завантажувачі OpenClaw SDK; -прямі імпорти з `dist/extensions/...` оминають поетапні дзеркала залежностей середовища виконання, -які упаковані встановлення використовують для залежностей, якими володіє Plugin. +активному знімку конфігурації середовища виконання, коли OpenClaw уже працює. Якщо знімка середовища виконання +ще немає, вони повертаються до розв’язаної конфігурації на диску. +Запаковані фасади вбудованих плагінів слід завантажувати через завантажувачі фасадів плагінів +OpenClaw; прямі імпорти з `dist/extensions/...` оминають staged-дзеркала залежностей середовища виконання, +які запаковані встановлення використовують для залежностей, що належать плагіну. -Plugin провайдерів можуть надавати вузький локальний для Plugin contract barrel, коли -допоміжний засіб навмисно специфічний для провайдера і ще не належить до загального підшляху SDK. +Плагіни провайдерів можуть відкривати вузький локальний для плагіна barrel контракту, коли +помічник навмисно специфічний для провайдера й поки що не належить до загального підшляху SDK. Вбудовані приклади: -- **Anthropic**: публічний шов `api.ts` / `contract-api.ts` для beta-header Claude - і допоміжних засобів потоків `service_tier`. -- **`@openclaw/openai-provider`**: `api.ts` експортує побудовники провайдера, - допоміжні засоби типових моделей і побудовники realtime-провайдера. -- **`@openclaw/openrouter-provider`**: `api.ts` експортує побудовник провайдера, - а також допоміжні засоби onboarding/конфігурації. +- **Anthropic**: публічний шов `api.ts` / `contract-api.ts` для Claude + beta-header і помічників потоку `service_tier`. +- **`@openclaw/openai-provider`**: `api.ts` експортує побудовники провайдерів, + помічники типових моделей і побудовники провайдерів realtime. +- **`@openclaw/openrouter-provider`**: `api.ts` експортує побудовник провайдера + плюс помічники онбордингу/конфігурації. - Виробничому коду розширення також слід уникати імпортів `openclaw/plugin-sdk/`. - Якщо допоміжний засіб справді спільний, піднесіть його до нейтрального підшляху SDK, - такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або інша - поверхня, орієнтована на можливість, замість того щоб зв’язувати два Plugins між собою. + Production-коду розширень також слід уникати імпортів `openclaw/plugin-sdk/`. + Якщо помічник справді спільний, підніміть його до нейтрального підшляху SDK, + як-от `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої + поверхні, орієнтованої на можливість, замість зв’язування двох плагінів між собою. ## Пов’язане - + Параметри `definePluginEntry` і `defineChannelPluginEntry`. - + Повна довідка простору імен `api.runtime`. - + Пакування, маніфести та схеми конфігурації. - - Утиліти тестування та правила lint. + + Тестові утиліти та правила lint. - + Міграція із застарілих поверхонь. - + Глибока архітектура та модель можливостей. diff --git a/docs/uk/reference/openclaw-sdk-api-design.md b/docs/uk/reference/openclaw-sdk-api-design.md index 649b50a96..848848aac 100644 --- a/docs/uk/reference/openclaw-sdk-api-design.md +++ b/docs/uk/reference/openclaw-sdk-api-design.md @@ -1,30 +1,37 @@ --- read_when: - - Ви реалізуєте запропонований публічний SDK застосунку OpenClaw - - Вам потрібен чернетковий простір імен, подія, результат, артефакт, затвердження або контракт безпеки для SDK застосунку - - Ви порівнюєте ресурси протоколу Gateway з високорівневою обгорткою OpenClaw SDK -summary: Еталонний дизайн запропонованого публічного API SDK застосунку OpenClaw, таксономії подій, артефактів, схвалень і структури пакета -title: Дизайн API OpenClaw SDK + - Ви впроваджуєте запропонований публічний SDK застосунку OpenClaw + - Вам потрібен чернетковий контракт простору імен, події, результату, артефакту, затвердження або безпеки для SDK застосунку + - Ви порівнюєте ресурси протоколу Gateway з високорівневою обгорткою OpenClaw App SDK +sidebarTitle: App SDK API design +summary: Еталонний дизайн для публічного OpenClaw App SDK API, таксономії подій, артефактів, затверджень і структури пакета +title: Проєктування API SDK застосунків OpenClaw x-i18n: - generated_at: "2026-04-29T23:55:35Z" + generated_at: "2026-04-30T00:49:55Z" model: gpt-5.5 provider: openai - source_hash: c4dd0123581f4ba8332b6af9c673467092082a16488a61b5cbeac1b33e9a5dd1 + source_hash: cacc5329942798b6876dba6ab8d6a9193291ddda81db5cb2ed492cc42a810099 source_path: reference/openclaw-sdk-api-design.md workflow: 16 --- -Ця сторінка є докладним проєктом довідника API для запропонованого публічного -[OpenClaw SDK](/uk/concepts/openclaw-sdk). Вона навмисно відокремлена від -[plugin SDK](/uk/plugins/sdk-overview). +Ця сторінка є докладним проєктом довідника API для публічного +[OpenClaw App SDK](/uk/concepts/openclaw-sdk). Вона навмисно відокремлена від +[Plugin SDK](/uk/plugins/sdk-overview). -Публічний SDK застосунку має бути побудований у двох шарах: + + `@openclaw/sdk` — це зовнішній пакет застосунку/клієнта для взаємодії з + Gateway. `openclaw/plugin-sdk/*` — це внутрішньопроцесний контракт для створення Plugin. + Не імпортуйте підшляхи Plugin SDK із застосунків, яким потрібно лише запускати агентів. + + +Публічний SDK застосунку має бути побудований у два шари: 1. Низькорівневий згенерований клієнт Gateway. -2. Високорівнева ергономічна обгортка з обʼєктами `OpenClaw`, `Agent`, `Session`, `Run`, - `Task`, `Artifact`, `Approval` та `Environment`. +2. Високорівнева ергономічна обгортка з об’єктами `OpenClaw`, `Agent`, `Session`, `Run`, + `Task`, `Artifact`, `Approval` і `Environment`. -## Проєктування простору імен +## Проєкт простору імен Низькорівневі простори імен мають точно відповідати ресурсам Gateway: @@ -73,7 +80,7 @@ oc.environments.status(environmentId); // future API: current SDK throws unsuppo oc.environments.delete(environmentId); // future API: current SDK throws unsupported ``` -Високорівневі обгортки мають повертати обʼєкти, які роблять типові потоки зручними: +Високорівневі обгортки мають повертати об’єкти, які роблять поширені потоки зручними: ```typescript const run = await agent.run(inputOrParams); @@ -108,43 +115,43 @@ type OpenClawEvent = { }; ``` -`id` є курсором відтворення. Споживачі мають мати змогу повторно підключитися через -`events({ after: id })` і отримати пропущені події, якщо це дозволяє термін зберігання. +`id` — це курсор відтворення. Споживачі мають мати змогу повторно підключитися з +`events({ after: id })` і отримати пропущені події, якщо це дозволяє утримання. -Рекомендовані нормалізовані сімейства подій: +Рекомендовані сімейства нормалізованих подій: -| Подія | Значення | -| --------------------- | ---------------------------------------------------------- | -| `run.created` | Запуск прийнято. | -| `run.queued` | Запуск очікує на лінію сесії, runtime або середовище. | -| `run.started` | Runtime почав виконання. | -| `run.completed` | Запуск успішно завершився. | -| `run.failed` | Запуск завершився з помилкою. | -| `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` | Запуск або інструмент потребує схвалення. | -| `approval.resolved` | Схвалення надано, відхилено, прострочено або скасовано. | -| `question.requested` | Runtime просить користувача або застосунок-хост надати дані. | -| `question.answered` | Застосунок-хост надав відповідь. | -| `artifact.created` | Доступний новий артефакт. | -| `artifact.updated` | Наявний артефакт змінено. | -| `session.created` | Сесію створено. | -| `session.updated` | Метадані сесії змінено. | -| `session.compacted` | Відбулася Compaction сесії. | -| `task.updated` | Стан фонової задачі змінено. | -| `git.branch` | Runtime спостеріг або змінив стан гілки. | -| `git.diff` | Runtime створив або змінив diff. | -| `git.pr` | Runtime відкрив, оновив або повʼязав pull request. | +| Подія | Значення | +| --------------------- | ----------------------------------------------------------- | +| `run.created` | Запуск прийнято. | +| `run.queued` | Запуск очікує смуги сеансу, середовища виконання або оточення. | +| `run.started` | Середовище виконання почало виконання. | +| `run.completed` | Запуск успішно завершено. | +| `run.failed` | Запуск завершився з помилкою. | +| `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` | Запуск або інструмент потребує схвалення. | +| `approval.resolved` | Схвалення надано, відхилено, прострочено або скасовано. | +| `question.requested` | Середовище виконання запитує ввід у користувача або хост-застосунку. | +| `question.answered` | Хост-застосунок надав відповідь. | +| `artifact.created` | Доступний новий артефакт. | +| `artifact.updated` | Наявний артефакт змінено. | +| `session.created` | Сеанс створено. | +| `session.updated` | Метадані сеансу змінено. | +| `session.compacted` | Відбулася Compaction сеансу. | +| `task.updated` | Стан фонового завдання змінено. | +| `git.branch` | Середовище виконання виявило або змінило стан гілки. | +| `git.diff` | Середовище виконання створило або змінило diff. | +| `git.pr` | Середовище виконання відкрило, оновило або пов’язало pull request. | -Нативні для runtime корисні навантаження мають бути доступні через `raw`, але застосунки не повинні -розбирати `raw` для звичайного UI. +Власні корисні навантаження середовища виконання мають бути доступні через `raw`, але застосунки не повинні +парсити `raw` для звичайного UI. ## Контракт результату @@ -176,16 +183,17 @@ type RunResult = { Результат має бути простим і стабільним. Значення часових міток зберігають форму Gateway, тому поточні запуски на основі життєвого циклу зазвичай повідомляють числа мілісекунд епохи, -тоді як адаптери все ще можуть повертати ISO-рядки. Багатий UI, трасування інструментів і -нативні для runtime деталі належать до подій та артефактів. +тоді як адаптери все ще можуть показувати рядки ISO. Багатий UI, траси інструментів і +власні деталі середовища виконання належать до подій та артефактів. -`accepted` є нетермінальним результатом очікування: це означає, що дедлайн очікування Gateway +`accepted` — це нетермінальний результат очікування: він означає, що крайній термін очікування Gateway минув до того, як запуск створив завершення життєвого циклу або помилку. Його не можна трактувати як -`timed_out`; `timed_out` зарезервовано для запуску, який перевищив власний тайм-аут runtime. +`timed_out`; `timed_out` зарезервовано для запуску, який перевищив власний тайм-аут +середовища виконання. ## Схвалення та запитання -Схвалення мають бути сутностями першого класу, тому що агенти кодування постійно перетинають межі безпеки. +Схвалення мають бути першокласними, оскільки агенти коду постійно перетинають межі безпеки. ```typescript run.onApproval(async (request) => { @@ -199,17 +207,18 @@ run.onApproval(async (request) => { Події схвалення мають містити: -- id схвалення -- id запуску та id сесії +- ідентифікатор схвалення +- ідентифікатор запуску та ідентифікатор сеансу - тип запиту -- підсумок запитуваної дії +- зведення запитаної дії - назву інструмента або дію середовища - рівень ризику - доступні рішення - строк дії - чи можна повторно використати рішення -Запитання відокремлені від схвалень. Запитання просить у користувача або застосунку-хоста інформацію. Схвалення просить дозволу виконати дію. +Запитання відокремлені від схвалень. Запитання просить у користувача або хост-застосунку +інформацію. Схвалення просить дозвіл виконати дію. ## Модель ToolSpace @@ -225,14 +234,15 @@ for (const tool of tools.list()) { SDK має надавати: -- нормалізовані метадані інструментів -- джерело: OpenClaw, MCP, Plugin, канал, runtime або застосунок -- підсумок схеми +- нормалізовані метадані інструмента +- джерело: OpenClaw, MCP, Plugin, канал, середовище виконання або застосунок +- зведення схеми - політику схвалення -- сумісність із runtime -- чи інструмент прихований, readonly, здатний до запису або здатний до хост-дій +- сумісність із середовищем виконання +- чи є інструмент прихованим, лише для читання, здатним до запису або здатним працювати з хостом -Виклик інструментів через SDK має бути явним і обмеженим за областю. Більшість застосунків мають запускати агентів, а не викликати довільні інструменти напряму. +Виклик інструмента через SDK має бути явним і обмеженим за областю. Більшість застосунків мають +запускати агентів, а не напряму викликати довільні інструменти. ## Модель артефактів @@ -261,54 +271,54 @@ type ArtifactSummary = { }; ``` -Типові приклади: +Поширені приклади: - редагування файлів і згенеровані файли -- пакети patch +- пакети патчів - diff VCS - знімки екрана та медіавиводи -- журнали та пакети трасування +- журнали та пакети трас - посилання на pull request -- траєкторії runtime -- знімки робочих просторів керованих середовищ +- траєкторії середовища виконання +- знімки робочого простору керованого середовища -Доступ до артефактів має підтримувати редагування чутливих даних, зберігання та URL для завантаження без +Доступ до артефактів має підтримувати редагування чутливих даних, утримання та URL-адреси для завантаження без припущення, що кожен артефакт є звичайним локальним файлом. ## Модель безпеки -SDK застосунку має явно визначати повноваження. +SDK застосунку має явно описувати повноваження. -Рекомендовані області токена: +Рекомендовані області токенів: | Область | Дозволяє | | ------------------- | ---------------------------------------------------- | -| `agent.read` | Перелічувати й переглядати агентів. | -| `agent.run` | Запускати запуски. | -| `session.read` | Читати метадані та повідомлення сесій. | -| `session.write` | Створювати, надсилати до, форкати, compact і переривати сесії. | -| `task.read` | Читати стан фонових задач. | -| `task.write` | Скасовувати або змінювати політику сповіщень задач. | +| `agent.read` | Перелічувати та переглядати агентів. | +| `agent.run` | Запускати виконання. | +| `session.read` | Читати метадані та повідомлення сеансу. | +| `session.write` | Створювати, надсилати до, форкати, compact і переривати сеанси. | +| `task.read` | Читати стан фонового завдання. | +| `task.write` | Скасовувати або змінювати політику сповіщень завдань. | | `approval.respond` | Схвалювати або відхиляти запити. | -| `tools.invoke` | Викликати відкриті інструменти напряму. | -| `artifacts.read` | Перелічувати й завантажувати артефакти. | +| `tools.invoke` | Напряму викликати відкриті інструменти. | +| `artifacts.read` | Перелічувати та завантажувати артефакти. | | `environment.write` | Створювати або знищувати керовані середовища. | | `admin` | Адміністративні операції. | Типові значення: - без пересилання секретів за замовчуванням -- без необмеженого пропускання змінних середовища +- без необмеженого наскрізного передавання змінних середовища - посилання на секрети замість значень секретів -- явна політика sandbox і мережі -- явне зберігання віддаленого середовища -- схвалення для виконання на хості, якщо політика не доводить інше -- необроблені події runtime редагуються для вилучення чутливих даних перед виходом із Gateway, якщо викликач не має +- явна політика пісочниці та мережі +- явне утримання віддаленого середовища +- схвалення для виконання на хості, якщо політика не доводить протилежне +- сирі події середовища виконання редагуються до того, як залишають Gateway, якщо викликач не має сильнішої діагностичної області -## Провайдер керованого середовища +## Постачальник керованого середовища -Керовані агенти мають реалізовуватися як провайдери середовищ. +Керовані агенти мають бути реалізовані як постачальники середовищ. ```typescript type EnvironmentProvider = { @@ -326,60 +336,59 @@ type EnvironmentProvider = { }; ``` -Перша реалізація не обовʼязково має бути hosted SaaS. Вона може націлюватися на -наявні хости node, ефемерні робочі простори, runners у стилі CI або середовища -у стилі Testbox. Важливий контракт такий: +Перша реалізація не обов’язково має бути розміщеним SaaS. Вона може бути націлена на +наявні хости Node, ефемерні робочі простори, runner-и у стилі CI або середовища у стилі Testbox. +Важливий контракт такий: 1. підготувати робочий простір -2. привʼязати безпечне середовище й секрети -3. запустити запуск +2. прив’язати безпечне середовище та секрети +3. запустити виконання 4. транслювати події 5. зібрати артефакти -6. очистити або зберегти згідно з політикою +6. очистити або утримати відповідно до політики -Коли це стабілізується, hosted cloud service зможе реалізувати той самий контракт провайдера. +Коли це стане стабільним, розміщений хмарний сервіс зможе реалізувати той самий контракт +постачальника. -## Структура пакунків +## Структура пакетів -Рекомендовані пакунки: +Рекомендовані пакети: -| Пакунок | Призначення | -| ----------------------- | ------------------------------------------------------------- | +| Пакет | Призначення | +| ----------------------- | ------------------------------------------------------------ | | `@openclaw/sdk` | Публічний високорівневий SDK і згенерований низькорівневий клієнт Gateway. | -| `@openclaw/sdk-react` | Опціональні хуки React для dashboards і розробників застосунків. | +| `@openclaw/sdk-react` | Необов’язкові React-хуки для панелей керування та розробників застосунків. | | `@openclaw/sdk-testing` | Тестові помічники та фальшивий сервер Gateway для інтеграцій застосунків. | -У репозиторії вже є `openclaw/plugin-sdk/*` для plugins. Тримайте цей простір імен +У репозиторії вже є `openclaw/plugin-sdk/*` для Plugin. Тримайте цей простір імен окремо, щоб не плутати авторів Plugin із розробниками застосунків. ## Стратегія згенерованого клієнта -Низькорівневий клієнт має генеруватися з версійованих схем протоколу Gateway, -а потім обгортатися рукописними ергономічними класами. +Низькорівневий клієнт має генеруватися з версійованих схем протоколу Gateway, а потім обгортатися написаними вручну зручними класами. -Шарування: +Шари: -1. Джерело істини для схеми Gateway. -2. Згенерований низькорівневий клієнт TypeScript. -3. Валідатори часу виконання для зовнішніх вхідних даних і даних подій. -4. Високорівневі обгортки `OpenClaw`, `Agent`, `Session`, `Run`, `Task` і `Artifact` - . -5. Практичні приклади та інтеграційні тести. +1. Схеми Gateway як джерело істини. +2. Згенерований низькорівневий TypeScript-клієнт. +3. Валідатори часу виконання для зовнішніх вхідних даних і корисного навантаження подій. +4. Високорівневі обгортки `OpenClaw`, `Agent`, `Session`, `Run`, `Task` і `Artifact`. +5. Приклади рецептів і інтеграційні тести. Переваги: -- дрейф протоколу помітний +- розбіжність протоколу помітна - тести можуть порівнювати згенеровані методи з експортами Gateway -- SDK застосунку залишається незалежним від внутрішніх компонентів SDK Plugin +- SDK застосунку залишається незалежним від внутрішніх деталей Plugin SDK - низькорівневі споживачі все ще мають повний доступ до протоколу - високорівневі споживачі отримують невеликий продуктовий API -## Пов’язані документи +## Пов’язана документація -- [Дизайн SDK OpenClaw](/uk/concepts/openclaw-sdk) +- [SDK застосунку OpenClaw](/uk/concepts/openclaw-sdk) - [Довідник RPC Gateway](/uk/reference/rpc) - [Цикл агента](/uk/concepts/agent-loop) - [Середовища виконання агентів](/uk/concepts/agent-runtimes) - [Фонові завдання](/uk/automation/tasks) - [Агенти ACP](/uk/tools/acp-agents) -- [Огляд SDK Plugin](/uk/plugins/sdk-overview) +- [Огляд Plugin SDK](/uk/plugins/sdk-overview)