Building plugins

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

OpenClaw에 임베딩, 이미지 생성, 비디오 생성 또는 향후 벤더 기반 기능 영역과 같은 새로운 공유 도메인이 필요할 때 이것을 사용하세요.

규칙:

plugin = 소유권 경계
capability = 공유 코어 계약

벤더를 채널이나 도구에 직접 연결하는 것으로 시작하지 마세요. 기능을 정의하는 것부터 시작하세요.

기능을 만들어야 하는 경우

다음이 모두 참일 때 새 기능을 만드세요.

둘 이상의 벤더가 그럴듯하게 구현할 수 있다.
채널, 도구 또는 기능 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(...)를 노출합니다.
코어가 runtime.imageGeneration.generate(...)를 노출합니다.
openai, google, fal, minimax Plugin이 벤더 기반 구현을 등록합니다.
향후 벤더는 채널/도구를 변경하지 않고 동일한 계약을 등록합니다.

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

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

폴백과 정책이 명시적으로 유지되도록 이 둘을 분리해 두세요.

임베딩 공급자

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

메모리 검색은 일반 embeddingProviders를 사용할 수 있습니다. 이전 memoryEmbeddingProviders 계약은 기존 메모리 전용 공급자가 마이그레이션하는 동안의 지원 중단된 호환성입니다. 새 재사용 가능 임베딩 공급자는 embeddingProviders를 사용해야 합니다.

리뷰 체크리스트

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

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

PR이 기능 계층을 건너뛰고 벤더 동작을 채널/도구에 하드코딩한다면, 되돌려 보내고 먼저 계약을 정의하세요.