Plugin 아키텍처 내부

​

로드 파이프라인

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

​

Manifest-first 동작

• Plugin을 식별합니다
• 선언된 채널/Skills/config schema 또는 번들 기능을 탐색합니다
• plugins.entries.<id>.config를 검증합니다
• Control UI 라벨/placeholder를 보강합니다
• 설치/카탈로그 메타데이터를 표시합니다
• Plugin 런타임을 로드하지 않고도 가벼운 활성화 및 설정 descriptor를 유지합니다

• CLI 로딩은 요청된 기본 명령을 소유한 Plugin으로 범위를 좁힙니다
• 채널 설정/Plugin 확인은 요청된 채널 id를 소유한 Plugin으로 범위를 좁힙니다
• 명시적 provider 설정/런타임 확인은 요청된 provider id를 소유한 Plugin으로 범위를 좁힙니다

​

로더가 캐시하는 항목

• 탐색 결과
• 매니페스트 레지스트리 데이터
• 로드된 Plugin 레지스트리

• OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1 또는 OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1로 이 캐시를 비활성화할 수 있습니다.
• OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS 및 OPENCLAW_PLUGIN_MANIFEST_CACHE_MS로 캐시 기간을 조정합니다.

​

레지스트리 모델

• Plugin 레코드(식별자, 소스, 출처, 상태, 진단)
• 도구
• 레거시 훅 및 타입 지정 훅
• 채널
• provider
• gateway RPC 핸들러
• HTTP 라우트
• CLI registrar
• 백그라운드 서비스
• Plugin 소유 명령

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

​

대화 바인딩 콜백

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // 이제 이 plugin + 대화에 대한 바인딩이 존재합니다.
        console.log(event.binding?.conversationId);
        return;
      }

      // 요청이 거부되었습니다. 로컬 보류 상태를 모두 정리합니다.
      console.log(event.request.conversation.conversationId);
    });
  },
};

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

​

Provider 런타임 훅

• 매니페스트 메타데이터: 저비용 사전 런타임 조회용: providerAuthEnvVars, providerAuthAliases, providerAuthChoices, channelEnvVars.
• config 시점 훅: 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);
  },
});

​

내장 예시

​

런타임 도우미

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는 파일/voice-note 표면을 위한 일반 코어 TTS 출력 payload를 반환합니다.
• 코어 messages.tts 구성과 provider 선택을 사용합니다.
• PCM 오디오 버퍼 + 샘플 속도를 반환합니다. Plugin은 provider에 맞게 리샘플링/인코딩해야 합니다.
• listVoices는 provider별로 선택 사항입니다. 벤더 소유 음성 선택기 또는 설정 흐름에 사용하세요.
• 음성 목록에는 provider 인식 선택기를 위한 locale, gender, personality 태그 같은 더 풍부한 메타데이터가 포함될 수 있습니다.
• 현재 telephony는 OpenAI와 ElevenLabs를 지원합니다. 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 정책, 대체, 응답 전달은 코어에 유지하세요.
• 벤더 소유 합성 동작에는 speech provider를 사용하세요.
• 레거시 Microsoft edge 입력은 microsoft provider id로 정규화됩니다.
• 선호되는 소유권 모델은 회사 중심입니다. OpenClaw가 해당 기능 계약을 추가함에 따라 하나의 벤더 Plugin이 텍스트, 음성, 이미지, 미래의 미디어 provider까지 소유할 수 있습니다.

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

• 오케스트레이션, 대체, config, 채널 연결은 코어에 유지하세요.
• 벤더 동작은 provider Plugin에 유지하세요.
• 점진적 확장은 타입 지정된 상태를 유지해야 합니다: 새로운 선택적 메서드, 새로운 선택적 결과 필드, 새로운 선택적 기능.
• 비디오 생성도 이미 같은 패턴을 따릅니다:
  • 코어가 기능 계약과 런타임 도우미를 소유합니다
  • 벤더 Plugin이 api.registerVideoGenerationProvider(...)를 등록합니다
  • 기능/채널 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 { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // MIME을 안정적으로 추론할 수 없을 때 선택 사항:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.*는 이미지/오디오/비디오 이해를 위한 선호되는 공유 표면입니다.
• 코어 미디어 이해 오디오 구성(tools.media.audio)과 provider 대체 순서를 사용합니다.
• 전사 출력이 생성되지 않으면 { text: undefined }를 반환합니다(예: 입력이 건너뛰어졌거나 지원되지 않는 경우).
• api.runtime.stt.transcribeAudioFile(...)는 호환성 별칭으로 남아 있습니다.

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은 영구 세션 변경이 아니라 실행별 선택적 재정의입니다.
• OpenClaw는 신뢰된 호출자에 대해서만 이러한 재정의 필드를 적용합니다.
• Plugin 소유 대체 실행의 경우 운영자는 plugins.entries.<id>.subagent.allowModelOverride: true로 명시적으로 허용해야 합니다.
• plugins.entries.<id>.subagent.allowedModels를 사용해 신뢰된 Plugin을 특정 정식 provider/model 대상으로 제한하거나, 명시적으로 모든 대상을 허용하려면 "*"를 사용하세요.
• 신뢰되지 않은 Plugin subagent 실행도 계속 동작하지만, 재정의 요청은 조용히 대체되는 대신 거부됩니다.

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 선택, 자격 증명 확인, 공유 요청 시맨틱은 코어에 유지하세요.
• 벤더별 검색 전송에는 웹 검색 provider를 사용하세요.
• api.runtime.webSearch.*는 agent 도구 래퍼에 의존하지 않고 검색 동작이 필요한 기능/채널 Plugin을 위한 선호되는 공유 표면입니다.

​

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(...): 구성된 이미지 생성 provider 체인을 사용해 이미지를 생성합니다.
• listProviders(...): 사용 가능한 이미지 생성 provider와 해당 기능을 나열합니다.

​

Gateway HTTP 라우트

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" 라우트는 운영자 런타임 scope를 자동으로 받지 않습니다. 특권 있는 Gateway helper 호출이 아니라 Plugin 관리 webhook/서명 검증용입니다.
• auth: "gateway" 라우트는 Gateway 요청 런타임 scope 안에서 실행되지만, 그 scope는 의도적으로 보수적입니다:
  • 공유 secret bearer 인증(gateway.auth.mode = "token" / "password")은 호출자가 x-openclaw-scopes를 보내더라도 plugin-route 런타임 scope를 operator.write에 고정합니다
  • 신뢰된 identity 전달 HTTP 모드(예: trusted-proxy 또는 사설 ingress의 gateway.auth.mode = "none")는 헤더가 명시적으로 있을 때만 x-openclaw-scopes를 적용합니다
  • 이런 identity 전달 plugin-route 요청에서 x-openclaw-scopes가 없으면 런타임 scope는 operator.write로 대체됩니다
• 실용적인 규칙: gateway 인증 Plugin 라우트를 암시적인 관리자 표면으로 가정하지 마세요. 라우트에 관리자 전용 동작이 필요하다면 identity 전달 인증 모드를 요구하고 명시적인 x-openclaw-scopes 헤더 계약을 문서화하세요.

​

Plugin SDK import 경로

• index.js — 번들 Plugin 엔트리
• api.js — 도우미/타입 barrel
• runtime-api.js — 런타임 전용 barrel
• setup-entry.js — 설정 Plugin 엔트리

​

메시지 도구 schema

• 의미 기반 프레젠테이션 블록용 presentation (text, context, divider, buttons, select)
• 고정 전달 요청용 delivery-pin

​

채널 대상 확인

• messaging.inferTargetChatType({ to })는 정규화된 대상을 디렉터리 조회 전에 direct, group, channel 중 무엇으로 다룰지 결정합니다.
• messaging.targetResolver.looksLikeId(raw, normalized)는 입력이 디렉터리 검색 대신 바로 id 유사 확인으로 건너뛰어야 하는지 코어에 알려줍니다.
• messaging.targetResolver.resolveTarget(...)는 정규화 후 또는 디렉터리 미스 후 코어에 최종 provider 소유 확인이 필요할 때 Plugin 대체 경로입니다.
• messaging.resolveOutboundSessionRoute(...)는 대상이 확인된 뒤 provider별 세션 라우트 구성을 소유합니다.

• 피어/그룹 검색 전에 이루어져야 하는 범주 결정에는 inferTargetChatType을 사용합니다.
• “이를 명시적/네이티브 대상 id로 취급” 확인에는 looksLikeId를 사용합니다.
• 광범위한 디렉터리 검색이 아니라 provider별 정규화 대체 경로에는 resolveTarget을 사용합니다.
• 채팅 id, 스레드 id, JID, 핸들, 방 id 같은 provider 고유 id는 일반 SDK 필드가 아니라 target 값 또는 provider별 파라미터 안에 유지하세요.

​

config 기반 디렉터리

• 허용 목록 기반 DM 피어
• 구성된 채널/그룹 맵
• 계정 범위의 정적 디렉터리 대체 항목

• 쿼리 필터링
• 제한 적용
• 중복 제거/정규화 도우미
• ChannelDirectoryEntry[] 빌드

​

Provider 카탈로그

• 하나의 provider 항목에 대해 { provider }
• 여러 provider 항목에 대해 { providers }

• simple: 일반 API 키 또는 env 기반 provider
• profile: 인증 프로필이 있을 때 나타나는 provider
• paired: 관련된 여러 provider 항목을 합성하는 provider
• late: 다른 암시적 provider 이후의 마지막 단계

• discovery는 레거시 별칭으로 계속 동작합니다
• catalog와 discovery가 모두 등록되면 OpenClaw는 catalog를 사용합니다

​

읽기 전용 채널 검사

• resolveAccount(...)는 런타임 경로입니다. 자격 증명이 완전히 구체화되었다고 가정해도 되며 필요한 secret이 없으면 즉시 실패할 수 있습니다.
• openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, doctor/config 복구 흐름 같은 읽기 전용 명령 경로는 단지 구성을 설명하기 위해 런타임 자격 증명을 구체화할 필요가 없어야 합니다.

• 설명용 계정 상태만 반환합니다.
• enabled와 configured를 유지합니다.
• 관련 있는 경우 자격 증명 소스/상태 필드를 포함합니다. 예:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• 읽기 전용 사용 가능 여부를 보고하기 위해 원시 token 값을 반환할 필요는 없습니다. 상태 스타일 명령에는 tokenStatus: "available"(및 대응되는 소스 필드)만 반환하면 충분합니다.
• 자격 증명이 SecretRef를 통해 구성되었지만 현재 명령 경로에서 사용할 수 없으면 configured_unavailable을 사용하세요.

​

패키지 pack

{
  "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 (셀프 호스팅)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Nextcloud Talk webhook bot을 통한 셀프 호스팅 채팅.",
      "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", () => ({
    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", () => ({
    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. 코어 계약 정의 코어가 소유해야 하는 공유 동작을 결정합니다: 정책, 대체, config 병합, 수명 주기, 채널 대상 시맨틱, 런타임 도우미 형태.
2. 타입 지정된 Plugin 등록/런타임 표면 추가 가장 작지만 유용한 타입 지정 기능 표면으로 OpenClawPluginApi 및/또는 api.runtime를 확장합니다.
3. 코어 + 채널/기능 소비자 연결 채널과 기능 Plugin은 벤더 구현을 직접 import하지 말고, 코어를 통해 새 기능을 사용해야 합니다.
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의 소유권/계약 assertion
• 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);
  },
});

// feature/channel plugin용 공유 런타임 도우미
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

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

• 코어가 기능 계약 + 오케스트레이션을 소유
• 벤더 Plugin이 벤더 구현을 소유
• 기능/채널 Plugin이 런타임 도우미를 사용
• 계약 테스트가 소유권을 명시적으로 유지

​

관련 문서

• Plugin architecture — 공개 기능 모델 및 형태
• Plugin SDK subpaths
• Plugin SDK setup
• Building plugins