Plugin 아키텍처 내부

​

로드 파이프라인

1. 후보 Plugin 루트를 발견합니다
2. 네이티브 또는 호환 번들 매니페스트와 패키지 메타데이터를 읽습니다
3. 안전하지 않은 후보를 거부합니다
4. Plugin 설정(plugins.enabled, allow, deny, entries, slots, load.paths)을 정규화합니다
5. 각 후보의 활성화 여부를 결정합니다
6. 활성화된 네이티브 모듈을 로드합니다. 빌드된 번들 모듈은 네이티브 로더를 사용하고, 서드파티 로컬 소스 TypeScript는 비상용 Jiti 폴백을 사용합니다
7. 네이티브 register(api) 훅을 호출하고 등록 항목을 Plugin 레지스트리에 수집합니다
8. 레지스트리를 명령/런타임 표면에 노출합니다

​

매니페스트 우선 동작

• Plugin을 식별합니다
• 선언된 채널/Skills/설정 스키마 또는 번들 기능을 발견합니다
• plugins.entries.<id>.config를 검증합니다
• Control UI 레이블/플레이스홀더를 보강합니다
• 설치/카탈로그 메타데이터를 표시합니다
• Plugin 런타임을 로드하지 않고 저렴한 활성화 및 설정 설명자를 보존합니다

• CLI 로딩은 요청된 기본 명령을 소유한 Plugin으로 범위를 좁힙니다
• 채널 설정/Plugin 해석은 요청된 채널 id를 소유한 Plugin으로 범위를 좁힙니다
• 명시적 제공자 설정/런타임 해석은 요청된 제공자 id를 소유한 Plugin으로 범위를 좁힙니다
• Gateway 시작 계획은 명시적 시작 임포트와 시작 제외에 activation.onStartup을 사용합니다. 시작 메타데이터가 없는 Plugin은 더 좁은 활성화 트리거를 통해서만 로드됩니다

​

Plugin 캐시 경계

• PluginLoaderCacheState 및 호환 활성 런타임 레지스트리
• 동일한 런타임 표면을 반복해서 임포트하지 않기 위해 사용하는 jiti/모듈 캐시와 공개 표면 로더 캐시
• 설치된 Plugin 아티팩트를 위한 파일 시스템 캐시
• 경로 정규화 또는 중복 해석을 위한 호출별 단기 맵

• 검색 결과
• 직접 manifest 레지스트리
• 설치된 Plugin 인덱스에서 재구성된 manifest 레지스트리
• 제공자 소유자 조회, 모델 억제, 제공자 정책 또는 공개 아티팩트 메타데이터
• 변경된 manifest, 설치된 인덱스 또는 로드 경로가 다음 메타데이터 읽기에서 보여야 하는 기타 모든 manifest 파생 답변

​

레지스트리 모델

• Plugin 레코드(식별 정보, 소스, 출처, 상태, 진단)
• 도구
• 레거시 훅 및 형식화된 훅
• 채널
• 제공자
• Gateway RPC 핸들러
• HTTP 라우트
• CLI 등록자
• 백그라운드 서비스
• Plugin 소유 명령

• Plugin 모듈 -> 레지스트리 등록
• 코어 런타임 -> 레지스트리 소비

​

대화 바인딩 콜백

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" 또는 "denied"
• decision: "allow-once", "allow-always" 또는 "deny"
• binding: 승인된 요청에 대해 해결된 바인딩
• request: 원래 요청 요약, 분리 힌트, 발신자 ID 및 대화 메타데이터

​

제공자 런타임 훅

• 저렴한 사전 런타임 조회를 위한 manifest 메타데이터: setup.providers[].envVars, 지원 중단된 호환성 providerAuthEnvVars, providerAuthAliases, providerAuthChoices, channelEnvVars.
• 설정 시점 훅: catalog(레거시 discovery) 및 applyConfigDefaults.
• 런타임 훅: 인증, 모델 해석, 스트림 래핑, 사고 수준, 재생 정책, 사용량 엔드포인트를 다루는 40개 이상의 선택적 훅. 전체 목록은 훅 순서와 사용법을 참조하세요.

​

훅 순서와 사용법

​

Provider 예시

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

내장 예시

​

Runtime helper

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech는 file/voice-note surface용 일반 core TTS output payload를 반환합니다.
• core messages.tts configuration 및 provider selection을 사용합니다.
• PCM audio buffer + sample rate를 반환합니다. Plugin은 provider에 맞게 resample/encode해야 합니다.
• listVoices는 provider별 optional입니다. vendor 소유 voice picker 또는 setup flow에 사용하세요.
• Voice listing에는 provider-aware picker를 위한 locale, gender, personality tag 같은 더 풍부한 metadata가 포함될 수 있습니다.
• 현재 OpenAI와 ElevenLabs는 telephony를 지원합니다. Microsoft는 지원하지 않습니다.

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• TTS policy, fallback, reply delivery는 core에 유지하세요.
• vendor 소유 synthesis 동작에는 speech provider를 사용하세요.
• Legacy Microsoft edge input은 microsoft provider id로 정규화됩니다.
• 선호되는 ownership model은 company 중심입니다. 하나의 vendor Plugin이 OpenClaw가 해당 capability contract를 추가함에 따라 text, speech, image, future media provider를 소유할 수 있습니다.

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• orchestration, fallback, config, channel wiring은 core에 유지하세요.
• vendor 동작은 provider Plugin에 유지하세요.
• Additive expansion은 typed 상태를 유지해야 합니다. 새 optional method, 새 optional result field, 새 optional capability를 사용하세요.
• Video generation도 이미 같은 pattern을 따릅니다.
  • core가 capability contract와 runtime helper를 소유합니다
  • vendor Plugin은 api.registerVideoGenerationProvider(...)를 등록합니다
  • feature/channel Plugin은 api.runtime.videoGeneration.*를 사용합니다

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.5",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.*는 image/audio/video understanding을 위한 선호 shared surface입니다.
• extractStructuredWithModel(...)은 범위가 제한된 provider 소유 image-first extraction을 위한 Plugin-facing seam입니다. 최소 하나의 image input을 포함하세요. text input은 supplemental context입니다. product Plugin은 route와 schema를 소유하고, OpenClaw는 provider/runtime boundary를 소유합니다.
• core media-understanding audio configuration(tools.media.audio) 및 provider fallback order를 사용합니다.
• transcription output이 생성되지 않으면(예: skipped/unsupported input) { text: undefined }를 반환합니다.
• api.runtime.stt.transcribeAudioFile(...)은 compatibility alias로 남아 있습니다.

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider와 model은 run별 optional override이며, persistent session change가 아닙니다.
• OpenClaw는 trusted caller에 대해서만 이러한 override field를 적용합니다.
• Plugin 소유 fallback run의 경우, operator는 plugins.entries.<id>.subagent.allowModelOverride: true로 opt in해야 합니다.
• plugins.entries.<id>.subagent.allowedModels를 사용하여 trusted Plugin을 특정 canonical provider/model target으로 제한하거나, 명시적으로 모든 target을 허용하려면 "*"를 사용하세요.
• Untrusted Plugin subagent run은 계속 동작하지만, override request는 조용히 fallback하는 대신 거부됩니다.
• Plugin이 생성한 subagent session에는 생성한 Plugin id가 태그됩니다. Fallback api.runtime.subagent.deleteSession(...)은 해당 owned session만 삭제할 수 있습니다. 임의 session 삭제에는 여전히 admin-scoped Gateway request가 필요합니다.

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• provider selection, credential resolution, shared request semantics는 core에 유지하세요.
• vendor-specific search transport에는 web-search provider를 사용하세요.
• api.runtime.webSearch.*는 agent tool wrapper에 의존하지 않고 search behavior가 필요한 feature/channel Plugin을 위한 선호 shared surface입니다.

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): configured image-generation provider chain을 사용하여 image를 생성합니다.
• listProviders(...): 사용 가능한 image-generation provider와 해당 capability를 나열합니다.

​

Gateway HTTP route

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: Gateway HTTP 서버 아래의 라우트 경로입니다.
• auth: 필수입니다. 일반 Gateway 인증을 요구하려면 "gateway"를 사용하고, Plugin 관리 인증/Webhook 검증에는 "plugin"을 사용합니다.
• match: 선택 사항입니다. "exact"(기본값) 또는 "prefix"입니다.
• replaceExisting: 선택 사항입니다. 같은 Plugin이 자신의 기존 라우트 등록을 대체할 수 있게 합니다.
• handler: 라우트가 요청을 처리했을 때 true를 반환합니다.

• api.registerHttpHandler(...)는 제거되었으며 Plugin 로드 오류를 발생시킵니다. 대신 api.registerHttpRoute(...)를 사용하세요.
• Plugin 라우트는 auth를 명시적으로 선언해야 합니다.
• 정확히 같은 path + match 충돌은 replaceExisting: true가 아닌 한 거부되며, 한 Plugin은 다른 Plugin의 라우트를 대체할 수 없습니다.
• 서로 다른 auth 수준의 중첩 라우트는 거부됩니다. exact/prefix 폴스루 체인은 같은 인증 수준에서만 유지하세요.
• auth: "plugin" 라우트는 운영자 런타임 스코프를 자동으로 받지 않습니다. 이는 권한 있는 Gateway 헬퍼 호출이 아니라 Plugin 관리 Webhook/서명 검증을 위한 것입니다.
• auth: "gateway" 라우트는 Gateway 요청 런타임 스코프 안에서 실행되지만, 해당 스코프는 의도적으로 보수적입니다.
  • 공유 비밀 bearer 인증(gateway.auth.mode = "token" / "password")은 호출자가 x-openclaw-scopes를 보내더라도 Plugin 라우트 런타임 스코프를 operator.write로 고정합니다.
  • 신뢰할 수 있는 신원 포함 HTTP 모드(예: 비공개 ingress의 trusted-proxy 또는 gateway.auth.mode = "none")는 헤더가 명시적으로 있을 때만 x-openclaw-scopes를 존중합니다.
  • 이러한 신원 포함 Plugin 라우트 요청에서 x-openclaw-scopes가 없으면 런타임 스코프는 operator.write로 폴백합니다.
• 실무 규칙: Gateway 인증 Plugin 라우트가 암묵적인 관리자 표면이라고 가정하지 마세요. 라우트에 관리자 전용 동작이 필요하다면 신원 포함 인증 모드를 요구하고 명시적인 x-openclaw-scopes 헤더 계약을 문서화하세요.

​

Plugin SDK 가져오기 경로

• index.js — 번들 Plugin 진입점
• api.js — 헬퍼/타입 배럴
• runtime-api.js — 런타임 전용 배럴
• setup-entry.js — 설정 Plugin 진입점

​

메시지 도구 스키마

• 의미론적 presentation 블록(text, context, divider, buttons, select)에는 presentation
• 고정 전송 요청에는 delivery-pin

​

채널 대상 해석

• messaging.inferTargetChatType({ to })는 디렉터리 조회 전에 정규화된 대상을 direct, group, channel 중 무엇으로 처리할지 결정합니다.
• messaging.targetResolver.looksLikeId(raw, normalized)는 입력이 디렉터리 검색 대신 id 형태 해석으로 바로 건너뛰어야 하는지 core에 알려줍니다.
• messaging.targetResolver.reservedLiterals는 해당 공급자의 채널/세션 참조인 단순 단어를 나열합니다. 해석은 예약 리터럴을 거부하기 전에 구성된 디렉터리 항목을 보존하고, 그다음 디렉터리 미스에서 fail closed합니다.
• messaging.targetResolver.resolveTarget(...)는 정규화 후 또는 디렉터리 미스 후 core에 최종 공급자 소유 해석이 필요할 때의 Plugin 폴백입니다.
• messaging.resolveOutboundSessionRoute(...)는 대상이 해석된 뒤 공급자별 세션 라우트 구성을 소유합니다.

• peers/groups 검색 전에 일어나야 하는 범주 결정에는 inferTargetChatType을 사용하세요.
• “이를 명시적/네이티브 대상 id로 처리” 확인에는 looksLikeId를 사용하세요.
• 넓은 디렉터리 검색이 아니라 공급자별 정규화 폴백에는 resolveTarget을 사용하세요.
• chat id, thread id, JID, handle, room id 같은 공급자 네이티브 id는 일반 SDK 필드가 아니라 target 값 또는 공급자별 매개변수 안에 유지하세요.

​

구성 기반 디렉터리

• allowlist 기반 DM peers
• 구성된 채널/그룹 맵
• 계정 범위 정적 디렉터리 폴백

• 쿼리 필터링
• limit 적용
• 중복 제거/정규화 헬퍼
• ChannelDirectoryEntry[] 빌드

​

공급자 카탈로그

• 하나의 공급자 항목에는 { provider }
• 여러 공급자 항목에는 { providers }

• simple: 일반 API 키 또는 env 기반 공급자
• profile: 인증 프로필이 있을 때 나타나는 공급자
• paired: 여러 관련 공급자 항목을 합성하는 공급자
• late: 다른 암시적 공급자 뒤의 마지막 패스

• discovery는 레거시 alias로 여전히 동작하지만 사용 중단 경고를 냅니다.
• catalog와 discovery가 모두 등록되면 OpenClaw는 catalog를 사용합니다.
• augmentModelCatalog는 사용 중단되었습니다. 번들 공급자는 registerModelCatalogProvider를 통해 보충 행을 게시해야 합니다.

​

읽기 전용 채널 검사

• resolveAccount(...)는 런타임 경로입니다. 자격 증명이 완전히 materialized되었다고 가정할 수 있으며, 필요한 비밀이 없을 때 빠르게 실패할 수 있습니다.
• openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, doctor/config repair 흐름 같은 읽기 전용 명령 경로는 구성을 설명하기 위해 런타임 자격 증명을 materialize할 필요가 없어야 합니다.

• 설명적인 계정 상태만 반환합니다.
• enabled와 configured를 보존합니다.
• 관련 있을 때 다음과 같은 자격 증명 source/status 필드를 포함합니다.
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• 읽기 전용 가용성을 보고하기 위해 원시 토큰 값을 반환할 필요는 없습니다. tokenStatus: "available"(및 일치하는 source 필드)을 반환하는 것으로 status 스타일 명령에는 충분합니다.
• 자격 증명이 SecretRef를 통해 구성되었지만 현재 명령 경로에서 사용할 수 없을 때는 configured_unavailable을 사용하세요.

​

패키지 팩

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• 채널 등록 자체
• Gateway가 수신을 시작하기 전에 사용할 수 있어야 하는 모든 HTTP 라우트
• 같은 기간 동안 존재해야 하는 모든 Gateway 메서드, 도구 또는 서비스

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

{
  "name": "@scope/my-channel",
  "openclaw": {
    "extensions": ["./index.ts"],
    "setupEntry": "./setup-entry.ts",
    "startup": {
      "deferConfiguredChannelFullLoadUntilAfterListen": true
    }
  }
}

​

채널 카탈로그 메타데이터

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Nextcloud Talk webhook 봇을 통한 자체 호스팅 채팅입니다.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: 더 풍부한 카탈로그/상태 표면을 위한 보조 레이블
• docsLabel: 문서 링크의 링크 텍스트 재정의
• preferOver: 이 카탈로그 항목이 우선해야 하는 낮은 우선순위의 Plugin/채널 ID
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: 선택 표면 문구 제어
• markdownCapable: 아웃바운드 서식 결정에서 채널을 마크다운 가능으로 표시
• exposure.configured: false로 설정하면 구성된 채널 목록 표면에서 채널 숨김
• exposure.setup: false로 설정하면 대화형 설정/구성 선택기에서 채널 숨김
• exposure.docs: 문서 탐색 표면에서 채널을 내부/비공개로 표시
• showConfigured / showInSetup: 호환성을 위해 여전히 허용되는 레거시 별칭. exposure 사용을 권장
• quickstartAllowFrom: 채널을 표준 빠른 시작 allowFrom 플로에 참여시킴
• forceAccountBinding: 계정이 하나만 존재하더라도 명시적 계정 바인딩 요구
• preferSessionLookupForAnnounceTarget: 공지 대상을 해석할 때 세션 조회 선호

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

컨텍스트 엔진 Plugin

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

새 기능 추가

1. 코어 계약 정의 코어가 소유해야 하는 공유 동작을 결정하세요: 정책, 폴백, 구성 병합, 수명 주기, 채널 대상 의미론, 런타임 헬퍼 형태.
2. 타입이 지정된 Plugin 등록/런타임 표면 추가 가장 작고 유용한 타입 지정 기능 표면으로 OpenClawPluginApi 및/또는 api.runtime을 확장하세요.
3. 코어 + 채널/기능 소비자 연결 채널과 기능 Plugin은 벤더 구현을 직접 가져오는 대신 코어를 통해 새 기능을 소비해야 합니다.
4. 벤더 구현 등록 그런 다음 벤더 Plugin이 해당 기능에 백엔드를 등록합니다.
5. 계약 커버리지 추가 시간이 지나도 소유권과 등록 형태가 명시적으로 유지되도록 테스트를 추가하세요.

​

기능 체크리스트

• src/<capability>/types.ts의 코어 계약 타입
• src/<capability>/runtime.ts의 코어 러너/런타임 헬퍼
• src/plugins/types.ts의 Plugin API 등록 표면
• src/plugins/registry.ts의 Plugin 레지스트리 연결
• 기능/채널 Plugin이 이를 소비해야 할 때 src/plugins/runtime/*의 Plugin 런타임 노출
• src/test-utils/plugin-registration.ts의 캡처/테스트 헬퍼
• src/plugins/contracts/registry.ts의 소유권/계약 어설션
• docs/의 운영자/Plugin 문서

​

기능 템플릿

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• core는 기능 계약과 오케스트레이션을 소유합니다.
• 벤더 Plugin은 벤더 구현을 소유합니다.
• 기능/channel Plugin은 런타임 헬퍼를 사용합니다.
• 계약 테스트는 소유권을 명시적으로 유지합니다.

​

관련 항목

• Plugin 아키텍처 — 공개 기능 모델과 형태
• Plugin SDK 하위 경로
• Plugin SDK 설정
• Plugin 빌드하기