Plugin 내부 구조

​

공개 기능 모델

​

외부 호환성 방침

​

Plugin 형태

​

레거시 훅

• 계속 작동하도록 유지
• 레거시로 문서화
• 모델/제공자 재정의 작업에는 before_model_resolve 우선 사용
• 프롬프트 변경 작업에는 before_prompt_build 우선 사용
• 실제 사용량이 감소하고 픽스처 적용 범위로 마이그레이션 안전성이 입증된 후에만 제거

​

호환성 신호

​

아키텍처 개요

• 구문 분석 시점 메타데이터는 registerCli(..., { descriptors: [...] })에서 가져옵니다.
• 실제 Plugin CLI 모듈은 지연 상태를 유지하다가 처음 호출될 때 등록될 수 있습니다.

• 매니페스트/구성 검증은 Plugin 코드를 실행하지 않고 매니페스트/스키마 메타데이터만으로 작동해야 합니다.
• 네이티브 기능 검색은 활성화하지 않는 레지스트리 스냅샷을 구축하기 위해 신뢰할 수 있는 Plugin 진입점 코드를 로드할 수 있습니다.
• 네이티브 런타임 동작은 api.registrationMode === "full"인 Plugin 모듈의 register(api) 경로에서 제공됩니다.

​

Plugin 메타데이터 스냅샷 및 조회 테이블

• 채널 소유권
• 지연된 채널 시작
• 시작 Plugin ID
• 제공자 및 CLI 백엔드 소유권
• 설정 제공자, 명령 별칭, 모델 카탈로그 제공자 및 매니페스트 계약 소유권
• Plugin 구성 스키마 및 채널 구성 스키마 검증
• 시작 시 자동 활성화 결정

​

활성화 계획

• activation.* 필드는 명시적인 플래너 힌트입니다
• providers, channels, commandAliases, setup.providers, contracts.tools 및 훅은 계속 매니페스트 소유권 폴백으로 사용됩니다
• 기존 호출자를 위해 ID 전용 플래너 API를 계속 사용할 수 있습니다
• 계획 API는 진단 과정에서 명시적 힌트와 소유권 폴백을 구분할 수 있도록 사유 레이블을 보고합니다

​

채널 Plugin과 공유 메시지 도구

• 코어는 공유 message 도구 호스트, 프롬프트 연결, 세션/스레드 기록 관리 및 실행 디스패치를 소유합니다
• 채널 Plugin은 범위가 지정된 작업 탐색, 기능 탐색 및 모든 채널별 스키마 조각을 소유합니다
• 채널 Plugin은 대화 ID가 스레드 ID를 인코딩하거나 상위 대화에서 상속되는 방식과 같은 제공자별 세션 대화 문법을 소유합니다
• 채널 Plugin은 작업 어댑터를 통해 최종 작업을 실행합니다

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• 신뢰할 수 있는 인바운드 requesterSenderId

• outbound.sendPoll은 공통 투표 모델에 맞는 채널을 위한 공유 기준 경로입니다
• actions.handleAction("poll")은 채널별 투표 의미 체계 또는 추가 투표 매개변수를 위한 권장 경로입니다

​

기능 소유권 모델

• 회사 Plugin은 일반적으로 해당 회사의 모든 OpenClaw 연동 표면을 소유해야 합니다
• 기능 Plugin은 일반적으로 자신이 도입한 전체 기능 표면을 소유해야 합니다
• 채널은 제공자 동작을 임의로 다시 구현하는 대신 공유 코어 기능을 사용해야 합니다

• 공급업체의 OpenClaw 연동 표면은 텍스트 모델, 음성, 이미지 및 동영상에 걸쳐 있더라도 하나의 Plugin에 존재합니다
• 다른 공급업체도 자체 표면 영역에 대해 동일한 방식을 사용할 수 있습니다
• 채널은 어느 공급업체 Plugin이 제공자를 소유하는지 신경 쓰지 않고, 코어가 노출하는 공유 기능 계약을 사용합니다

• Plugin = 소유권 경계
• 기능 = 여러 Plugin이 구현하거나 사용할 수 있는 코어 계약

​

기능 계층화

• 코어는 응답 시점의 TTS 정책, 폴백 순서, 환경설정 및 채널 전달을 소유합니다
• elevenlabs, google, microsoft, openai는 합성 구현을 소유합니다
• voice-call은 전화 통신 TTS 런타임 도우미를 사용합니다

​

다중 기능 회사 Plugin 예시

import type { OpenClawPluginDefinition } from "openclaw/plugin-sdk/plugin-entry";
import {
  describeImageWithModel,
  transcribeOpenAiCompatibleAudio,
} from "openclaw/plugin-sdk/media-understanding";
import { createPluginBackedWebSearchProvider } from "openclaw/plugin-sdk/provider-web-search";

const plugin: OpenClawPluginDefinition = {
  id: "exampleai",
  name: "ExampleAI",
  register(api) {
    api.registerProvider({
      id: "exampleai",
      // auth/model catalog/runtime hooks
    });

    api.registerSpeechProvider({
      id: "exampleai",
      // vendor speech config — implement the SpeechProviderPlugin interface directly
    });

    api.registerMediaUnderstandingProvider({
      id: "exampleai",
      capabilities: ["image", "audio", "video"],
      async describeImage(req) {
        return describeImageWithModel({
          ...req,
          provider: "exampleai",
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          ...req,
          provider: "exampleai",
        });
      },
    });

    api.registerWebSearchProvider(
      createPluginBackedWebSearchProvider({
        id: "exampleai-search",
        // credential + fetch logic
      }),
    );
  },
};

export default plugin;

• 하나의 Plugin이 공급업체 표면을 소유합니다
• 코어는 계속 기능 계약을 소유합니다
• 채널과 기능 Plugin은 공급업체 코드가 아니라 api.runtime.* 도우미를 사용합니다
• 계약 테스트는 Plugin이 소유한다고 명시한 기능을 등록했는지 검증할 수 있습니다

​

기능 예시: 동영상 이해

​

계약 및 적용

• Plugin 작성자는 하나의 안정적인 내부 표준을 사용할 수 있습니다
• 코어는 두 Plugin이 동일한 공급자 ID를 등록하는 등의 소유권 중복을 거부할 수 있습니다
• 시작 시 잘못된 형식의 등록에 대해 조치 가능한 진단을 표시할 수 있습니다
• 계약 테스트는 번들 Plugin 소유권을 강제하고 의도치 않은 변경을 방지할 수 있습니다

​

계약에 포함해야 하는 항목

​

실행 모델

​

내보내기 경계

• 번들 Plugin 전용 헬퍼 하위 경로
• 공개 API로 제공할 목적이 아닌 런타임 배관 하위 경로
• 공급업체별 편의 헬퍼
• 구현 세부 사항인 설정/온보딩 헬퍼

​

내부 구조 및 참고 자료

​

관련 문서

• Plugin 빌드
• Plugin 매니페스트
• Plugin SDK 설정