Добавление возможностей (руководство для контрибьюторов)

Используйте это, когда OpenClaw требуется новая общая предметная область, например embeddings, генерация изображений, генерация видео или какая-либо будущая область возможностей, поддерживаемая поставщиком. Правило:

• Plugin = граница владения
• возможность = общий контракт ядра

Не начинайте с прямого подключения поставщика к каналу или инструменту. Начните с определения возможности.

​

Когда создавать возможность

Создавайте новую возможность, когда все перечисленное верно:

1. Ее потенциально может реализовать более одного поставщика.
2. Каналы, инструменты или функциональные Plugin должны потреблять ее, не заботясь о поставщике.
3. Ядро должно владеть fallback-поведением, политикой, конфигурацией или поведением доставки.

Если работа относится только к поставщику и общего контракта пока нет, остановитесь и сначала определите контракт.

​

Стандартная последовательность

1. Определите типизированный контракт ядра.
2. Добавьте регистрацию Plugin для этого контракта.
3. Добавьте общий вспомогательный runtime-модуль.
4. Подключите один реальный Plugin поставщика как доказательство.
5. Переведите потребителей функций/каналов на вспомогательный runtime-модуль.
6. Добавьте контрактные тесты.
7. Задокументируйте конфигурацию для операторов и модель владения.

​

Что куда относится

Ядро:

• Типы запросов/ответов.
• Реестр поставщиков + разрешение.
• Fallback-поведение.
• Схема конфигурации с распространяемыми метаданными документации title / description для вложенного объекта, wildcard, элемента массива и узлов композиции.
• Поверхность вспомогательного runtime-модуля.

Plugin поставщика:

• Вызовы API поставщика.
• Обработка аутентификации поставщика.
• Нормализация запросов, специфичная для поставщика.
• Регистрация реализации возможности.

Функциональный/канальный Plugin:

• Вызывает api.runtime.* или соответствующий вспомогательный модуль plugin-sdk/*-runtime.
• Никогда не вызывает реализацию поставщика напрямую.

​

Стыки поставщика и обвязки

Используйте хуки поставщика, когда поведение относится к контракту поставщика модели, а не к общему циклу агента. Примеры включают специфичные для поставщика параметры запроса после выбора транспорта, предпочтение auth-профиля, наложения prompt и маршрутизацию последующего fallback после failover модели/профиля. Используйте хуки обвязки агента, когда поведение относится к runtime, который выполняет ход. Обвязки могут классифицировать явные результаты протокола, такие как пустой вывод, reasoning без видимого вывода или структурированный план без финального ответа, чтобы внешняя политика fallback модели могла принять решение о повторной попытке. Держите оба стыка узкими:

• Ядро владеет политикой повторных попыток/fallback.
• Plugin поставщиков владеют специфичными для поставщика подсказками запроса/аутентификации/маршрутизации.
• Plugin обвязок владеют специфичной для runtime классификацией попыток.
• Сторонние Plugin возвращают подсказки, а не прямые изменения состояния ядра.

​

Контрольный список файлов

Для новой возможности ожидайте изменения в этих областях:

• src/<capability>/types.ts
• src/<capability>/...registry/runtime.ts
• src/plugins/types.ts
• src/plugins/registry.ts
• src/plugins/captured-registration.ts
• src/plugins/contracts/registry.ts
• src/plugins/runtime/types-core.ts
• src/plugins/runtime/index.ts
• src/plugin-sdk/<capability>.ts
• src/plugin-sdk/<capability>-runtime.ts
• Один или несколько встроенных пакетов Plugin.
• Конфигурация, документация, тесты.

​

Рабочий пример: генерация изображений

Генерация изображений следует стандартной форме:

1. Ядро определяет ImageGenerationProvider.
2. Ядро предоставляет registerImageGenerationProvider(...).
3. Ядро предоставляет runtime.imageGeneration.generate(...).
4. Plugin openai, google, fal и minimax регистрируют реализации, поддерживаемые поставщиками.
5. Будущие поставщики регистрируют тот же контракт без изменения каналов/инструментов.

Ключ конфигурации намеренно отделен от маршрутизации анализа изображений:

• agents.defaults.imageModel анализирует изображения.
• agents.defaults.imageGenerationModel генерирует изображения.

Держите их раздельными, чтобы fallback и политика оставались явными.

​

Поставщики embeddings

Используйте embeddingProviders для переиспользуемых поставщиков векторных embeddings. Этот контракт намеренно шире, чем память: инструменты, поиск, retrieval, импортеры или будущие функциональные Plugin могут потреблять embeddings, не завися от движка памяти. Поиск по памяти может потреблять универсальные embeddingProviders. Более старый контракт memoryEmbeddingProviders является устаревшей совместимостью, пока существующие поставщики, специфичные для памяти, мигрируют; новые переиспользуемые поставщики embeddings должны использовать embeddingProviders.

​

Контрольный список проверки

Перед поставкой новой возможности проверьте:

• Ни один канал/инструмент не импортирует код поставщика напрямую.
• Вспомогательный runtime-модуль является общим путем.
• Как минимум один контрактный тест проверяет встроенное владение.
• Документация конфигурации называет новую модель/ключ конфигурации.
• Документация Plugin объясняет границу владения.

Если PR пропускает слой возможностей и жестко встраивает поведение поставщика в канал/инструмент, верните его и сначала определите контракт.

​

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

• Внутреннее устройство Plugin — модель возможностей, владение, конвейер загрузки, вспомогательные runtime-модули.
• Создание Plugin — руководство по первому Plugin.
• Обзор SDK — справочник по карте импортов и API регистрации.
• Создание Skills — сопутствующая поверхность для участников разработки.