English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Plugins

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

OpenClaw에 이미지 생성, 비디오 생성 또는 향후 벤더 기반 기능 영역 같은 새 공유 도메인이 필요할 때 이 문서를 사용하세요.

규칙:

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

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

기능을 생성해야 하는 경우

다음 조건이 모두 참일 때 새 기능을 생성하세요.

  1. 둘 이상의 벤더가 그 기능을 구현할 가능성이 있습니다.
  2. 채널, 도구 또는 기능 Plugin이 벤더를 신경 쓰지 않고 이를 사용할 수 있어야 합니다.
  3. 코어가 폴백, 정책, 설정 또는 전달 동작을 소유해야 합니다.

작업이 벤더 전용이고 아직 공유 계약이 없다면 중단하고 먼저 계약을 정의하세요.

표준 순서

  1. 타입이 지정된 코어 계약을 정의합니다.
  2. 해당 계약에 대한 Plugin 등록을 추가합니다.
  3. 공유 런타임 헬퍼를 추가합니다.
  4. 증명으로 실제 벤더 Plugin 하나를 연결합니다.
  5. 기능/채널 소비자를 런타임 헬퍼로 이동합니다.
  6. 계약 테스트를 추가합니다.
  7. 운영자 대상 설정과 소유권 모델을 문서화합니다.

위치별 책임

코어:

  • 요청/응답 타입.
  • 제공자 레지스트리 + 해석.
  • 폴백 동작.
  • 중첩 객체, 와일드카드, 배열 항목, 컴포지션 노드에 전파된 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 패키지.
  • 설정, 문서, 테스트.

작업 예시: 이미지 생성

이미지 생성은 표준 형태를 따릅니다.

  1. 코어가 ImageGenerationProvider를 정의합니다.
  2. 코어가 registerImageGenerationProvider(...)를 노출합니다.
  3. 코어가 runtime.imageGeneration.generate(...)를 노출합니다.
  4. openai, google, fal, minimax Plugin이 벤더 기반 구현을 등록합니다.
  5. 향후 벤더는 채널/도구를 변경하지 않고 동일한 계약을 등록합니다.

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

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

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

리뷰 체크리스트

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

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

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

관련