Plugin 내부

​

공개 기능 모델

​

외부 호환성 입장

​

Plugin 형태

​

레거시 hook

• 계속 동작하게 유지
• 레거시로 문서화
• 모델/provider override 작업에는 before_model_resolve 선호
• prompt mutation 작업에는 before_prompt_build 선호
• 실제 사용량이 줄고 fixture coverage가 migration 안전성을 증명한 뒤에만 제거

​

호환성 신호

​

아키텍처 개요

• parse-time metadata는 registerCli(..., { descriptors: [...] })에서 가져옵니다.
• 실제 Plugin CLI module은 lazy 상태를 유지하고 첫 invocation 때 등록될 수 있습니다.

• manifest/config 검증은 Plugin code를 실행하지 않고 manifest/schema metadata에서 동작해야 합니다.
• 네이티브 기능 discovery는 trusted Plugin entry code를 로드해 non-activating registry snapshot을 만들 수 있습니다.
• 네이티브 runtime 동작은 api.registrationMode === "full"인 Plugin module의 register(api) 경로에서 나옵니다.

​

Plugin metadata snapshot 및 lookup table

• channel ownership
• deferred channel startup
• startup Plugin id
• provider 및 CLI backend ownership
• setup provider, command alias, model catalog provider, manifest contract ownership
• Plugin config schema 및 channel config schema 검증
• startup auto-enable 결정

​

Activation planning

• activation.* 필드는 명시적인 플래너 힌트입니다
• providers, channels, commandAliases, setup.providers, contracts.tools, 훅은 manifest 소유권 fallback으로 남습니다
• ID 전용 플래너 API는 기존 호출자에게 계속 제공됩니다
• plan API는 진단에서 명시적 힌트와 소유권 fallback을 구분할 수 있도록 reason label을 보고합니다

​

채널 Plugin과 공유 메시지 도구

• 코어는 공유 message 도구 호스트, 프롬프트 연결, 세션/스레드 bookkeeping, 실행 dispatch를 소유합니다
• 채널 Plugin은 범위가 지정된 action discovery, capability discovery, 채널별 schema fragment를 소유합니다
• 채널 Plugin은 conversation id가 thread id를 인코딩하거나 parent conversation에서 상속하는 방식 같은 provider별 세션 conversation grammar를 소유합니다
• 채널 Plugin은 action adapter를 통해 최종 action을 실행합니다

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• 신뢰된 inbound requesterSenderId

• outbound.sendPoll은 공통 poll model에 맞는 채널을 위한 공유 baseline입니다
• actions.handleAction("poll")은 채널별 poll semantic이나 추가 poll parameter를 위한 권장 경로입니다

​

Capability 소유권 모델

• 회사 Plugin은 일반적으로 해당 회사의 OpenClaw-facing surface 전체를 소유해야 합니다
• 기능 Plugin은 일반적으로 자신이 도입하는 전체 feature surface를 소유해야 합니다
• 채널은 provider behavior를 ad hoc으로 다시 구현하는 대신 공유 코어 capability를 사용해야 합니다

• OpenAI는 text model, speech, image, 향후 video에 걸쳐 있더라도 하나의 Plugin에 있습니다
• 다른 vendor도 자신의 surface area에 대해 같은 방식을 사용할 수 있습니다
• 채널은 어떤 vendor Plugin이 provider를 소유하는지 신경 쓰지 않고, 코어가 노출하는 공유 capability contract를 사용합니다

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

​

Capability layering

• 코어는 reply-time TTS policy, fallback order, pref, channel delivery를 소유합니다
• openai, elevenlabs, microsoft는 synthesis implementation을 소유합니다
• voice-call은 telephony TTS runtime helper를 사용합니다

​

Multi-capability company Plugin 예시

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

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({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
      async transcribeAudio(req) {
        return transcribeOpenAiCompatibleAudio({
          provider: "exampleai",
          model: req.model,
          input: req.input,
        });
      },
    });

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

export default plugin;

• 하나의 Plugin이 vendor surface를 소유합니다
• 코어는 여전히 capability contract를 소유합니다
• 채널과 기능 Plugin은 vendor code가 아니라 api.runtime.* helper를 사용합니다
• contract test는 Plugin이 소유한다고 주장하는 capability를 register했는지 assert할 수 있습니다

​

Capability 예시: video understanding

​

Contract와 enforcement

• Plugin author는 하나의 안정적인 internal standard를 얻습니다
• 코어는 같은 provider id를 두 Plugin이 register하는 것 같은 중복 소유권을 거절할 수 있습니다
• startup은 잘못된 registration에 대해 actionable diagnostic을 표시할 수 있습니다
• contract test는 bundled-Plugin ownership을 enforce하고 silent drift를 방지할 수 있습니다

​

계약에 포함되어야 하는 것

​

실행 모델

​

내보내기 경계

• 번들된 Plugin별 헬퍼 하위 경로
• 공개 API로 의도되지 않은 런타임 배관 하위 경로
• 벤더별 편의 헬퍼
• 구현 세부 사항인 setup/onboarding 헬퍼

​

내부 구조 및 참고 자료

​

관련 항목

• Plugin 빌드
• Plugin 매니페스트
• Plugin SDK setup