Обзор SDK плагинов

SDK плагинов — это типизированный контракт между плагинами и ядром. Эта страница — справочник по тому, что импортировать и что можно регистрировать.

Соглашение об импорте

Всегда импортируйте из конкретного подпути:

Каждый подпуть представляет собой небольшой автономный модуль. Это ускоряет запуск и предотвращает проблемы с циклическими зависимостями. Для специфичных для канала вспомогательных средств точки входа и сборки предпочитайте 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 для сохраняемых схем встроенных каналов. Устаревшие экспорты совместимости остаются в plugin-sdk/channel-config-schema-legacy; ни один из подпутей встроенных схем не является образцом для новых плагинов.

Справочник подпутей

SDK плагинов предоставляется в виде набора узких подпутей, сгруппированных по областям (точка входа плагина, канал, провайдер, аутентификация, среда выполнения, возможность, память и зарезервированные вспомогательные средства встроенных плагинов). Полный каталог с группировкой и ссылками см. в разделе Подпути SDK плагинов.

Перечень точек входа компилятора находится в scripts/lib/plugin-sdk-entrypoints.json; экспорты пакета генерируются из общедоступного подмножества после исключения локальных для репозитория тестовых и внутренних подпутей, перечисленных в scripts/lib/plugin-sdk-private-local-only-subpaths.json. Выполните pnpm plugin-sdk:surface, чтобы проверить количество общедоступных экспортов. Устаревшие общедоступные подпути, которые достаточно давно существуют и не используются рабочим кодом встроенных расширений, отслеживаются в scripts/lib/plugin-sdk-deprecated-public-subpaths.json; широкие устаревшие реэкспортирующие модули отслеживаются в scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json.

API регистрации

Функция обратного вызова register(api) получает объект OpenClawPluginApi со следующими методами:

Регистрация возможностей

Провайдеры рабочих процессов также должны объявить свой идентификатор в contracts.workerProviders. Ядро сохраняет устойчивое намерение до provision(profile, operationId). Провайдеры проверяют настройки до внешнего выделения ресурсов и создают исключение WorkerProviderError при окончательном отклонении профиля. provision должен повторно использовать ту же аренду при повторении идентификатора операции. Ядро сохраняет проверенные настройки профиля вместе с арендой и передаёт этот снимок в destroy({ leaseId, profile }), который должен быть идемпотентным, и в inspect({ leaseId, profile }), который возвращает active, destroyed или unknown. Это позволяет провайдерам маршрутизировать вызовы жизненного цикла после перезапуска Gateway или удаления именованного профиля. Конечные точки SSH используют SecretRef для keyRef, никогда не используют ключевой материал непосредственно и включают hostKey из доверенного результата подготовки ресурсов в точности как algorithm base64, без имени хоста или комментария. Ядро закрепляет hostKey и никогда не доверяет ключу, полученному при первом подключении. Провайдер, создающий динамический keyRef, может реализовать resolveSshIdentity({ leaseId, profile, keyRef }); при его наличии этот механизм разрешения является определяющим, а провайдеры без него используют настроенный универсальный механизм разрешения секретов. Провайдеры с возобновляемыми арендами также могут реализовать renew(leaseId). inspect должен создавать исключение при временных или неопределённых сбоях; возвращайте unknown только при достоверно подтверждённом отсутствии. Ядро помечает активную локальную запись как оставшуюся без владельца или считает отсутствие завершением удаления после сохранённого запроса на уничтожение.

Провайдеры вложений, зарегистрированные с помощью api.registerEmbeddingProvider(...), должны также быть перечислены в contracts.embeddingProviders в манифесте плагина. Это универсальный интерфейс вложений для повторно используемой генерации векторов. Поиск по памяти может использовать этот универсальный интерфейс провайдера. Прежний интерфейс api.registerMemoryEmbeddingProvider(...) и contracts.memoryEmbeddingProviders является устаревшим интерфейсом совместимости на время миграции существующих провайдеров, специфичных для памяти.

Провайдеры, специфичные для памяти, которые всё ещё предоставляют batchEmbed(...) среды выполнения, остаются на существующем контракте пакетной обработки по отдельным файлам, если их среда выполнения явно не задаёт sourceWideBatchEmbed: true. Этот параметр позволяет узлу памяти передавать фрагменты из нескольких изменённых файлов памяти и включённых источников в одном вызове batchEmbed(...) в пределах пакетных ограничений узла. Пакетные адаптеры, загружающие файлы запросов JSONL, должны разделять задания провайдера как до достижения ограничения размера загрузки, так и до достижения ограничения количества запросов. Провайдер должен возвращать по одному вложению на каждый входной фрагмент в том же порядке, что и batch.chunks; не указывайте этот флаг, если провайдер ожидает пакеты в пределах одного файла или не может сохранять порядок входных данных в более крупном задании, охватывающем весь источник.

Инструменты и команды

Используйте defineToolPlugin для простых плагинов, содержащих только инструменты с фиксированными именами инструментов. Используйте api.registerTool(...) напрямую для смешанных плагинов или полностью динамической регистрации инструментов.

Команды плагинов могут задавать agentPromptGuidance, когда агенту нужна краткая принадлежащая команде подсказка маршрутизации. Этот текст должен описывать саму команду; не добавляйте специфичную для провайдера или плагина политику в построители основных подсказок.

Рекомендации могут быть устаревшими строками, применяемыми ко всем поверхностям подсказок, или структурированными записями:

agentPromptGuidance: [  "Глобальная подсказка команды.",  { text: "Показывать это только в основной подсказке OpenClaw.", surfaces: ["openclaw_main"] },];

Структурированный surfaces может включать openclaw_main, codex_app_server, cli_backend, acp_backend или subagent. pi_main остаётся устаревшим псевдонимом для openclaw_main. Не указывайте surfaces для рекомендаций, намеренно предназначенных для всех поверхностей. Не передавайте пустой массив surfaces; он отклоняется, чтобы случайная потеря области действия не превращала текст в глобальную подсказку.

Инструкции разработчика нативного сервера приложения Codex строже, чем у других поверхностей подсказок: в этот канал с более высоким приоритетом продвигаются только рекомендации, область действия которых явно ограничена codex_app_server. Устаревшие строковые рекомендации и структурированные рекомендации без указанной области действия для совместимости остаются доступными поверхностям подсказок, не относящимся к Codex.

Команды узла-хоста выполняются на подключённом узле-хосте, а не внутри процесса Gateway. Если присутствует agentTool, Node публикует дескриптор после успешного подключения к Gateway; Gateway предоставляет его запускам агентов, только пока этот Node подключён и только если command дескриптора входит в утверждённую поверхность команд Node. Установите agentTool.defaultPlatforms, чтобы включить неопасную команду в стандартный список разрешённых команд Node; в противном случае требуется явный gateway.nodes.allowCommands или политика вызова Node. agentTool.name должен быть безопасным для провайдера: начинаться с буквы, содержать только буквы, цифры, символы подчёркивания или дефисы и иметь длину не более 64 символов. Инструменты Node на основе MCP могут задавать метаданные agentTool.mcp, чтобы поверхности каталога и поиска инструментов могли показывать идентичность удалённого сервера/инструмента MCP, но выполнение по-прежнему проходит через объявленную команду Node.

Инфраструктура

Построители дополнительных разделов промпта памяти получают необязательный контекст agentId, agentSessionKey и sandboxed. Вызовы search и get для дополнительного корпуса памяти получают необязательный контекст agentId и sandboxed. Плагины с хранилищем, принадлежащим агенту, должны определять это хранилище для каждого вызова, а не сохранять один глобальный путь при регистрации. Если идентификатор агента требуется, но отсутствует в операции с несколькими агентами, следует завершить работу с отказом, а не выбирать произвольного агента.

Интерактивные обработчики Telegram могут возвращать { submitText }, чтобы направить текст через обычный входящий путь агента Telegram после успешного завершения обработчика. OpenClaw сохраняет кнопку обратного вызова, если политика входящих сообщений пропускает текст или обработка завершается ошибкой, чтобы пользователь мог повторить попытку после изменения блокирующего условия. Это поле результата специфично для Telegram; другие каналы сохраняют собственные контракты интерактивных результатов.

Перехватчики хоста для плагинов рабочих процессов

Перехватчики хоста — это интерфейсы SDK для плагинов, которым необходимо участвовать в жизненном цикле хоста, а не только добавлять поставщика, канал или инструмент. Это универсальные контракты; их может использовать режим планирования, а также рабочие процессы подтверждения, проверки политик рабочей области, фоновые мониторы, мастера настройки и плагины-компаньоны пользовательского интерфейса.

Дескриптор surface: "tab" добавляет вкладку на боковую панель Control UI. Дескрипторы вкладок активных плагинов передаются клиентам панели управления в приветствии Gateway (controlUiTabs), поэтому вкладка отображается только при включённом плагине. Встроенные плагины могут предоставлять полноценное представление панели управления для своей вкладки; другие плагины могут задать path как HTTP-маршрут плагина (см. api.registerHttpRoute(...)), который панель управления отображает в изолированном фрейме. icon — это подсказка имени значка панели управления, group выбирает раздел боковой панели (control или agent), order задаёт порядок среди вкладок плагинов, а requiredScopes скрывает вкладку от подключений, не имеющих указанных областей доступа оператора:

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Журнал",  description: "Ваш день в виде временной шкалы, созданной из снимков экрана.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

Для нового кода плагинов используйте сгруппированные пространства имён:

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

Эквивалентные плоские методы остаются доступными как устаревшие псевдонимы совместимости для существующих плагинов. Не добавляйте новый код плагинов, напрямую вызывающий api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn или api.unscheduleSessionTurnsByTag.

scheduleSessionTurn(...) — это удобная обёртка уровня сеанса над планировщиком Cron в Gateway. Cron управляет временем и создаёт запись фоновой задачи при выполнении хода; Plugin SDK лишь ограничивает целевой сеанс, принадлежащие плагину именование и очистку. Используйте api.runtime.tasks.managedFlows внутри запланированного хода, когда самой работе требуется устойчивое многошаговое состояние потока задач.

Контракты намеренно разделяют полномочия:

• Внешние плагины могут управлять расширениями сеансов, дескрипторами пользовательского интерфейса, командами, метаданными инструментов, внедрениями в следующий ход и обычными перехватчиками.
• Доверенные политики инструментов выполняются до обычных перехватчиков before_tool_call и пользуются доверием хоста. Политики встроенных плагинов выполняются первыми; политики установленных плагинов требуют явного включения и указания их локальных идентификаторов в contracts.trustedToolPolicies, после чего выполняются в порядке загрузки плагинов. Идентификаторы политик ограничены областью зарегистрировавшего их плагина.
• Владение зарезервированными командами доступно только встроенным плагинам. Внешним плагинам следует использовать собственные имена команд или псевдонимы.
• allowPromptInjection=false отключает перехватчики, изменяющие промпты, включая agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, поля промптов из устаревшего before_agent_start и enqueueNextTurnInjection.

Примеры потребителей, не относящихся к режиму планирования:

Регистрация обнаружения Gateway

api.registerGatewayDiscoveryService(...) позволяет плагину объявить активный Gateway в локальном механизме обнаружения, например mDNS/Bonjour. OpenClaw вызывает сервис во время запуска Gateway, когда локальное обнаружение включено, передаёт текущие порты Gateway и несекретные данные-подсказки TXT, а во время завершения работы Gateway вызывает возвращённый обработчик stop.

api.registerGatewayDiscoveryService({  id: "my-discovery",  async advertise(ctx) {    const handle = await startMyAdvertiser({      gatewayPort: ctx.gatewayPort,      tls: ctx.gatewayTlsEnabled,      displayName: ctx.machineDisplayName,    });    return { stop: () => handle.stop() };  },});

Плагины обнаружения Gateway не должны считать объявляемые значения TXT секретами или средством аутентификации. Обнаружение служит подсказкой для маршрутизации; за доверие по-прежнему отвечают аутентификация Gateway и привязка TLS.

Метаданные регистрации CLI

api.registerCli(registrar, opts?) принимает два вида метаданных команд:

• commands: явные имена команд, принадлежащие регистратору
• descriptors: дескрипторы команд времени разбора, используемые для справки CLI, маршрутизации и отложенной регистрации CLI плагина
• parentPath: необязательный путь родительской команды для вложенных групп команд, например ["nodes"]

Для функций сопряжённых узлов предпочитайте api.registerNodeCliFeature(registrar, opts?). Это небольшая обёртка над api.registerCli(..., { parentPath: ["nodes"] }), которая явно определяет такие команды, как openclaw nodes canvas, в качестве принадлежащих плагину функций узлов.

Если команда плагина должна оставаться отложенно загружаемой в обычном корневом пути CLI, укажите descriptors, охватывающие каждый корень команды верхнего уровня, предоставляемый этим регистратором.

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Управление учётными записями Matrix, проверкой, устройствами и состоянием профиля",        hasSubcommands: true,      },    ],  },);

Вложенные команды получают разрешённую родительскую команду как program:

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Захват или отрисовка содержимого холста с сопряжённого узла",        hasSubcommands: true,      },    ],  },);

Используйте только commands, лишь когда отложенная регистрация корневого CLI не нужна. Этот путь совместимости с немедленной загрузкой по-прежнему поддерживается, но не устанавливает заполнители на основе дескрипторов для отложенной загрузки во время разбора.

Регистрация бэкенда CLI

api.registerCliBackend(...) позволяет плагину владеть конфигурацией по умолчанию для локального бэкенда CLI с ИИ, например claude-cli или my-cli.

• Идентификатор бэкенда id становится префиксом провайдера в ссылках на модели, таких как my-cli/gpt-5.
• Конфигурация бэкенда config имеет ту же структуру, что и agents.defaults.cliBackends.<id>.
• Пользовательская конфигурация по-прежнему имеет приоритет. Перед запуском CLI OpenClaw объединяет agents.defaults.cliBackends.<id> с конфигурацией плагина по умолчанию, применяя пользовательские значения поверх неё.
• Используйте normalizeConfig, когда бэкенду после объединения требуется преобразование для совместимости (например, нормализация старых форм флагов).
• Используйте resolveExecutionArgs для относящихся к запросу преобразований argv, которые принадлежат диалекту CLI, например для сопоставления уровней рассуждения OpenClaw с нативным флагом интенсивности. Хук получает ctx.executionMode; используйте "side-question", чтобы добавить нативные для бэкенда флаги изоляции для эфемерных вызовов /btw. Если эти флаги надёжно отключают нативные инструменты для CLI, в котором они иначе всегда включены, также объявите sideQuestionToolMode: "disabled".
• Используйте prepareExecution для принадлежащего бэкенду окружения запуска или временных мостов аутентификации/конфигурации. Его ctx.contextTokenBudget — это фактический лимит токенов, выбранный для запуска, благодаря чему бэкенды с нативной Compaction могут согласовать собственный порог без специфичных для провайдера ветвей в ядре.
• Бэкенды, способные отключить все нативные инструменты для конкретного запуска, могут объявить nativeToolMode: "selectable". Ограниченные вызовы передают пустой кортеж ctx.toolAvailability.native вместе с точным списком разрешённых MCP, изолированным на уровне хоста; resolveExecutionArgs должен обеспечить соблюдение обоих ограничений в итоговом argv для нового или возобновлённого запуска. Если бэкенд не может это сделать, OpenClaw блокирует выполнение.

Полное руководство по созданию см. в разделе Плагины бэкендов CLI.

Эксклюзивные слоты

Устаревшие адаптеры векторных представлений памяти

• registerMemoryCapability — предпочтительный эксклюзивный API плагина памяти.
• registerMemoryCapability также может предоставлять publicArtifacts.listArtifacts(...), чтобы сопутствующие плагины могли получать экспортированные артефакты памяти через openclaw/plugin-sdk/memory-host-core, не обращаясь к закрытой структуре каталогов конкретного плагина памяти.
• registerMemoryPromptSection, registerMemoryFlushPlan и registerMemoryRuntime — эксклюзивные API плагинов памяти с поддержкой устаревшей совместимости.
• MemoryFlushPlan.model может привязать ход сброса к точной ссылке provider/model, например ollama/qwen3:8b, не наследуя активную цепочку резервных вариантов.
• registerMemoryEmbeddingProvider устарел. Новые провайдеры векторных представлений должны использовать api.registerEmbeddingProvider(...) и contracts.embeddingProviders.
• Существующие провайдеры, специфичные для памяти, продолжают работать в течение периода миграции, однако для плагинов, не входящих в комплект, проверка плагинов сообщает об этом как о долге совместимости.

События и жизненный цикл

Примеры, распространённые имена хуков и семантику защитных условий см. в разделе Хуки плагинов.

Семантика решений хуков

before_install — хук жизненного цикла среды выполнения плагина, а не интерфейс политики установки оператора. Используйте security.installPolicy, когда решение о разрешении или блокировке должно охватывать пути установки или обновления через CLI и Gateway.

• before_tool_call: возврат { block: true } является окончательным. Как только любой обработчик задаёт это значение, обработчики с более низким приоритетом пропускаются.
• before_tool_call: возврат { block: false } рассматривается как отсутствие решения (аналогично отсутствию block), а не как переопределение.
• before_install: возврат { block: true } является окончательным. Как только любой обработчик задаёт это значение, обработчики с более низким приоритетом пропускаются.
• before_install: возврат { block: false } рассматривается как отсутствие решения (аналогично отсутствию block), а не как переопределение.
• reply_dispatch: возврат { handled: true, ... } является окончательным. Как только любой обработчик принимает диспетчеризацию на себя, обработчики с более низким приоритетом и стандартный путь диспетчеризации модели пропускаются.
• message_sending: возврат { cancel: true } является окончательным. Как только любой обработчик задаёт это значение, обработчики с более низким приоритетом пропускаются.
• message_sending: возврат { cancel: false } рассматривается как отсутствие решения (аналогично отсутствию cancel), а не как переопределение.
• message_received: используйте типизированное поле threadId, когда требуется маршрутизация входящих веток/тем. Сохраняйте metadata для дополнений, специфичных для канала.
• message_sending: используйте типизированные поля маршрутизации replyToId / threadId, прежде чем переходить к специфичному для канала metadata.
• gateway_start: используйте ctx.config, ctx.workspaceDir и ctx.getCron?.() для принадлежащего Gateway состояния запуска вместо зависимости от внутренних хуков gateway:startup. На этом этапе Cron всё ещё может загружаться.
• cron_reconciled: перестраивает полную внешнюю проекцию Cron после запуска или перезагрузки планировщика. Она включает reason и фактическое состояние enabled, включая enabled: false, а ctx.getCron?.() возвращает точный согласованный планировщик. Передавайте ctx.abortSignal в операции с сохраняемой проекцией; выполнение прерывается, когда этот снимок планировщика заменяется более новым или Gateway закрывается.
• cron_changed: отслеживает принадлежащие Gateway изменения жизненного цикла Cron. События scheduled и removed являются подсказками для согласования после фиксации, а не упорядоченным журналом изменений. В запланированном событии event.nextRunAtMs отсутствует, если у задания нет следующего пробуждения; событие удаления по-прежнему содержит снимок удалённого задания.

Внешние планировщики пробуждений должны применять задержку или объединять события cron_changed, а затем повторно считывать полное сохраняемое представление из планировщика, последним захваченного cron_reconciled. Не используйте планировщик из контекста cron_changed: отдельная подсказка от старого планировщика может пересечься с более поздней перезагрузкой.

Используйте cron_reconciled как триггер полного снимка для сохраняемого состояния, загруженного при запуске Gateway или замене планировщика. Он не воспроизводится при горячей перезагрузке только плагина. Обработчики наблюдения выполняются параллельно, а диспетчеризации без ожидания результата могут перекрываться, поэтому потребители не должны зависеть от порядка завершения событий. OpenClaw должен оставаться источником истины для проверки наступления срока и выполнения.

Описание адаптера с единственным параллельным выполнением, сохраняемой заменой, повторными попытками/задержкой и корректным завершением работы см. в разделе Безопасная внешняя проекция Cron.

Поля объекта API

Соглашение для внутренних модулей

Внутри плагина используйте локальные файлы реэкспорта для внутренних импортов:

my-plugin/  api.ts            # Публичные экспорты для внешних потребителей  runtime-api.ts    # Внутренние экспорты только для среды выполнения  index.ts          # Точка входа плагина  setup-entry.ts    # Облегчённая точка входа только для настройки (необязательно)

Публичные интерфейсы встроенных плагинов, загружаемые через фасад (api.ts, runtime-api.ts, index.ts, setup-entry.ts и аналогичные публичные файлы точек входа), предпочитают активный снимок конфигурации среды выполнения, если OpenClaw уже запущен. Если снимка среды выполнения ещё нет, они используют разрешённый файл конфигурации на диске. Фасады упакованных встроенных плагинов следует загружать через фасадные загрузчики плагинов OpenClaw; прямые импорты из dist/extensions/... обходят проверки манифеста и сопутствующего файла среды выполнения, которые упакованные установки используют для кода, принадлежащего плагину.

Плагины провайдеров могут предоставлять узкий локальный файл реэкспорта контракта плагина, если вспомогательное средство намеренно специфично для провайдера и пока не относится к универсальному подпути SDK. Примеры встроенных плагинов:

• Anthropic: публичный интерфейс api.ts / contract-api.ts для вспомогательных средств бета-заголовков Claude и потоковой передачи service_tier.
• @openclaw/openai-provider: api.ts экспортирует построители провайдеров, вспомогательные средства моделей по умолчанию и построители провайдеров реального времени.
• @openclaw/openrouter-provider: api.ts экспортирует построитель провайдера, а также вспомогательные средства первоначальной настройки и конфигурации.

Связанные материалы