chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
1228bc109f
commit
28a192e600
@ -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 через стабільний
|
||||
<Note>
|
||||
Використовуйте `@openclaw/sdk`, коли зовнішній застосунок, скрипт, dashboard, CI job або IDE
|
||||
extension хоче запускати агентів OpenClaw і спостерігати за ними через Gateway. Використовуйте
|
||||
`openclaw/plugin-sdk/*` лише під час написання Plugin, який працює всередині OpenClaw.
|
||||
</Note>
|
||||
|
||||
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)
|
||||
|
||||
@ -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 і ядром. Ця сторінка є
|
||||
довідником щодо **того, що імпортувати** і **що можна реєструвати**.
|
||||
|
||||
<Note>
|
||||
Ця сторінка призначена для авторів plugins, які використовують `openclaw/plugin-sdk/*` всередині
|
||||
OpenClaw. Для зовнішніх застосунків, скриптів, панелей керування, завдань CI та розширень IDE,
|
||||
які хочуть запускати агентів через Gateway, натомість використовуйте
|
||||
[OpenClaw App SDK](/uk/concepts/openclaw-sdk) і пакет `@openclaw/sdk`.
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
Шукаєте натомість практичний посібник? Почніть із [Створення плагінів](/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 інструментів або хуків життєвого циклу.
|
||||
</Tip>
|
||||
|
||||
## Угода про імпорт
|
||||
## Угода щодо імпорту
|
||||
|
||||
Завжди імпортуйте з конкретного підшляху:
|
||||
|
||||
@ -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.
|
||||
|
||||
<Warning>
|
||||
Не імпортуйте зручні 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.
|
||||
</Warning>
|
||||
|
||||
## Довідник підшляхів
|
||||
|
||||
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 |
|
||||
|
||||
<Note>
|
||||
Зарезервовані 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.
|
||||
</Note>
|
||||
|
||||
<Accordion title="Коли використовувати middleware результатів інструментів">
|
||||
Вбудовані плагіни можуть використовувати `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 було вилучено.
|
||||
</Accordion>
|
||||
|
||||
### Реєстрація виявлення 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.<id>`.
|
||||
- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.<id>` поверх
|
||||
типових налаштувань 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<string, unknown>` | Специфічна для Plugin конфігурація з `plugins.entries.<id>.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<string, unknown>` | Конфігурація, специфічна для плагіна, з `plugins.entries.<id>.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 # Полегшений вхід лише для налаштування (необов’язково)
|
||||
```
|
||||
|
||||
<Warning>
|
||||
Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/<your-plugin>`
|
||||
з виробничого коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK — лише зовнішній контракт.
|
||||
Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/<your-plugin>`
|
||||
з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або
|
||||
`./runtime-api.ts`. Шлях SDK є лише зовнішнім контрактом.
|
||||
</Warning>
|
||||
|
||||
Публічні поверхні вбудованих 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` експортує побудовник провайдера
|
||||
плюс помічники онбордингу/конфігурації.
|
||||
|
||||
<Warning>
|
||||
Виробничому коду розширення також слід уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо допоміжний засіб справді спільний, піднесіть його до нейтрального підшляху SDK,
|
||||
такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або інша
|
||||
поверхня, орієнтована на можливість, замість того щоб зв’язувати два Plugins між собою.
|
||||
Production-коду розширень також слід уникати імпортів `openclaw/plugin-sdk/<other-plugin>`.
|
||||
Якщо помічник справді спільний, підніміть його до нейтрального підшляху SDK,
|
||||
як-от `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої
|
||||
поверхні, орієнтованої на можливість, замість зв’язування двох плагінів між собою.
|
||||
</Warning>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Entry points" icon="door-open" href="/uk/plugins/sdk-entrypoints">
|
||||
<Card title="Точки входу" icon="door-open" href="/uk/plugins/sdk-entrypoints">
|
||||
Параметри `definePluginEntry` і `defineChannelPluginEntry`.
|
||||
</Card>
|
||||
<Card title="Runtime helpers" icon="gears" href="/uk/plugins/sdk-runtime">
|
||||
<Card title="Помічники середовища виконання" icon="gears" href="/uk/plugins/sdk-runtime">
|
||||
Повна довідка простору імен `api.runtime`.
|
||||
</Card>
|
||||
<Card title="Setup and config" icon="sliders" href="/uk/plugins/sdk-setup">
|
||||
<Card title="Налаштування й конфігурація" icon="sliders" href="/uk/plugins/sdk-setup">
|
||||
Пакування, маніфести та схеми конфігурації.
|
||||
</Card>
|
||||
<Card title="Testing" icon="vial" href="/uk/plugins/sdk-testing">
|
||||
Утиліти тестування та правила lint.
|
||||
<Card title="Тестування" icon="vial" href="/uk/plugins/sdk-testing">
|
||||
Тестові утиліти та правила lint.
|
||||
</Card>
|
||||
<Card title="SDK migration" icon="arrows-turn-right" href="/uk/plugins/sdk-migration">
|
||||
<Card title="Міграція SDK" icon="arrows-turn-right" href="/uk/plugins/sdk-migration">
|
||||
Міграція із застарілих поверхонь.
|
||||
</Card>
|
||||
<Card title="Plugin internals" icon="diagram-project" href="/uk/plugins/architecture">
|
||||
<Card title="Внутрішня архітектура плагінів" icon="diagram-project" href="/uk/plugins/architecture">
|
||||
Глибока архітектура та модель можливостей.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -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 застосунку має бути побудований у двох шарах:
|
||||
<Note>
|
||||
`@openclaw/sdk` — це зовнішній пакет застосунку/клієнта для взаємодії з
|
||||
Gateway. `openclaw/plugin-sdk/*` — це внутрішньопроцесний контракт для створення Plugin.
|
||||
Не імпортуйте підшляхи Plugin SDK із застосунків, яким потрібно лише запускати агентів.
|
||||
</Note>
|
||||
|
||||
Публічний 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)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user