Building plugins

기능 추가(기여자 가이드)

OpenClaw에 임베딩, 이미지 생성, 동영상 생성 또는 향후 공급업체가 지원하는 기능 영역과 같은 새로운 공유 도메인이 필요할 때 이 가이드를 사용하세요.

원칙:

Plugin = 소유권 경계
기능 = 공유 코어 계약

공급업체를 채널이나 도구에 직접 연결하지 마세요. 먼저 기능을 정의하세요.

기능을 생성해야 하는 경우

다음 조건을 모두 충족하는 경우에만 새 기능을 생성하세요.

둘 이상의 공급업체가 해당 기능을 구현할 가능성이 있어야 합니다.
채널, 도구 또는 기능 Plugin이 공급업체를 신경 쓰지 않고 해당 기능을 사용할 수 있어야 합니다.
코어가 폴백, 정책, 구성 또는 전달 동작을 소유해야 합니다.

작업이 특정 공급업체에만 해당하고 아직 공유 계약이 없다면 먼저 계약을 정의하세요.

표준 순서

타입이 지정된 코어 계약을 정의합니다.
해당 계약의 Plugin 등록을 추가합니다.
공유 런타임 헬퍼를 추가합니다.
실제 공급업체 Plugin 하나를 연결하여 입증합니다.
기능/채널 소비자가 런타임 헬퍼를 사용하도록 전환합니다.
계약 테스트를 추가합니다.
운영자용 구성과 소유권 모델을 문서화합니다.

구성 요소별 역할

계층	소유 범위
코어	요청/응답 타입, 제공자 레지스트리 및 해석, 폴백 동작, 중첩 객체·와일드카드·배열 항목·컴포지션 노드에 전파되는 `title`/`description` 문서 메타데이터를 포함한 구성 스키마, 런타임 헬퍼 표면.
공급업체 Plugin	공급업체 API 호출, 공급업체 인증 처리, 공급업체별 요청 정규화, 기능 구현 등록.
기능/채널 Plugin	`api.runtime.` 또는 이에 대응하는 `plugin-sdk/-runtime` 헬퍼를 호출합니다. 공급업체 구현을 직접 호출하지 않습니다.

제공자 및 하네스 경계

동작이 일반 에이전트 루프가 아닌 모델 제공자 계약에 속하는 경우 제공자 훅을 사용하세요. 예를 들어 전송 방식을 선택한 후의 제공자별 요청 매개변수, 인증 프로필 선호도, 프롬프트 오버레이, 모델/프로필 장애 조치 후의 후속 폴백 라우팅 등이 있습니다.

동작이 한 턴을 실행하는 런타임에 속하는 경우 에이전트 하네스 훅을 사용하세요. 하네스는 출력 없음, 표시되는 출력 없이 추론만 존재함, 최종 답변 없이 구조화된 계획만 존재함과 같은 명시적 프로토콜 결과를 분류하여 외부 모델 폴백 정책이 재시도 여부를 결정할 수 있게 합니다.

두 경계를 모두 좁게 유지하세요.

코어는 재시도/폴백 정책을 소유합니다.
제공자 Plugin은 제공자별 요청/인증/라우팅 힌트를 소유합니다.
하네스 Plugin은 런타임별 시도 분류를 소유합니다.
서드 파티 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 패키지.
구성, 문서, 테스트.

예제: 이미지 생성

이미지 생성은 표준 구조를 따릅니다.

코어가 ImageGenerationProvider를 정의합니다.
코어가 registerImageGenerationProvider(...)를 노출합니다.
코어가 api.runtime.imageGeneration.generate(...)와 .listProviders(...)를 노출합니다.
공급업체 Plugin(comfy, deepinfra, fal, google, litellm, microsoft-foundry, minimax, openai, openrouter, vydra, xai)이 공급업체 지원 구현을 등록합니다.
향후 공급업체는 채널/도구를 변경하지 않고 동일한 계약을 등록합니다.

구성 키는 의도적으로 비전 분석 라우팅과 분리되어 있습니다.

agents.defaults.imageModel은 이미지를 분석합니다.
agents.defaults.imageGenerationModel은 이미지를 생성합니다.

폴백과 정책을 명시적으로 유지할 수 있도록 두 항목을 분리하세요.

임베딩 제공자

재사용 가능한 벡터 임베딩 제공자에는 registerEmbeddingProvider(...) / 계약 embeddingProviders를 사용하세요. 이 계약은 의도적으로 메모리보다 범위가 넓습니다. 도구, 검색, 검색 증강, 임포터 또는 향후 기능 Plugin은 메모리 엔진에 의존하지 않고 임베딩을 사용할 수 있습니다. 메모리 검색도 범용 embeddingProviders를 사용합니다.

이전의 메모리 전용 등록 API 및 memoryEmbeddingProviders 계약은 더 이상 사용되지 않습니다. 모든 새 임베딩 제공자에는 registerEmbeddingProvider와 embeddingProviders를 사용하세요.

검토 체크리스트

새 기능을 출시하기 전에 다음 사항을 확인하세요.

어떤 채널/도구도 공급업체 코드를 직접 가져오지 않습니다.
런타임 헬퍼가 공유 경로입니다.
하나 이상의 계약 테스트가 번들 소유권을 검증합니다.
구성 문서에 새 모델/구성 키가 명시되어 있습니다.
Plugin 문서에 소유권 경계가 설명되어 있습니다.

PR이 기능 계층을 건너뛰고 공급업체 동작을 채널/도구에 하드코딩한다면 반려하고 먼저 계약을 정의하세요.