​

플러그인 내부 구조

​

공개 capability 모델

​

외부 호환성 입장

• 기존 외부 플러그인: hook 기반 통합이 계속 동작하도록 유지하며, 이를 호환성 기준선으로 취급합니다
• 새로운 번들/네이티브 플러그인: vendor별 직접 접근이나 새로운 hook-only 설계보다 명시적인 capability 등록을 우선합니다
• capability 등록을 도입하는 외부 플러그인: 허용되지만, 문서에서 명시적으로 안정된 계약으로 표시하지 않는 한 capability별 helper surface는 진화 중인 것으로 취급합니다

• capability 등록 API가 의도된 방향입니다
• 레거시 hook은 전환 기간 동안 외부 플러그인에 가장 안전한 무중단 경로로 남아 있습니다
• export된 helper subpath가 모두 동일한 것은 아닙니다. 우연히 export된 helper가 아니라, 문서화된 좁은 계약을 우선하세요

​

플러그인 형태

• plain-capability — 정확히 하나의 capability 타입만 등록합니다 (예: mistral 같은 provider 전용 플러그인)
• hybrid-capability — 여러 capability 타입을 등록합니다 (예: openai는 텍스트 추론, 음성, 미디어 이해, 이미지 생성을 소유)
• hook-only — hook만 등록하고, capability, tool, command, service는 등록하지 않습니다
• non-capability — tool, command, service, route는 등록하지만 capability는 등록하지 않습니다

​

레거시 hook

• 계속 동작하게 유지합니다
• 레거시로 문서화합니다
• 모델/provider override 작업에는 before_model_resolve를 우선합니다
• 프롬프트 변경 작업에는 before_prompt_build를 우선합니다
• 실제 사용량이 줄고 fixture 커버리지가 마이그레이션 안전성을 입증한 뒤에만 제거합니다

​

호환성 신호

​

아키텍처 개요

1. Manifest + discovery OpenClaw는 설정된 경로, workspace 루트, 전역 extension 루트, 번들 extension에서 후보 플러그인을 찾습니다. discovery는 먼저 네이티브 openclaw.plugin.json manifest와 지원되는 bundle manifest를 읽습니다.
2. 활성화 + 검증 core는 발견된 플러그인이 활성화, 비활성화, 차단, 또는 memory와 같은 독점 슬롯에 선택될지를 결정합니다.
3. 런타임 로드 네이티브 OpenClaw 플러그인은 jiti를 통해 in-process로 로드되며 중앙 레지스트리에 capability를 등록합니다. 호환 bundle은 런타임 코드를 import하지 않고 레지스트리 레코드로 정규화됩니다.
4. surface 소비 OpenClaw의 나머지 부분은 레지스트리를 읽어 tool, channel, provider 설정, hook, HTTP route, CLI command, service를 노출합니다.

• 파싱 시점 메타데이터는 registerCli(..., { descriptors: [...] })에서 옵니다
• 실제 플러그인 CLI 모듈은 lazy 상태를 유지하다가 첫 호출 시 등록될 수 있습니다

• discovery + config validation은 플러그인 코드를 실행하지 않고도 manifest/schema 메타데이터만으로 동작해야 합니다
• 네이티브 런타임 동작은 플러그인 모듈의 register(api) 경로에서 옵니다

​

채널 플러그인과 공유 message tool

• core는 공유 message tool 호스트, 프롬프트 연결, session/thread bookkeeping, 실행 dispatch를 소유합니다
• 채널 플러그인은 scope된 action discovery, capability discovery, 채널별 schema fragment를 소유합니다
• 채널 플러그인은 provider별 session conversation grammar를 소유합니다. 예를 들어 conversation id가 thread id를 인코딩하는 방식이나 부모 conversation에서 상속하는 방식이 여기에 해당합니다
• 채널 플러그인은 action adapter를 통해 최종 action을 실행합니다

• accountId
• currentChannelId
• currentThreadTs
• currentMessageId
• sessionKey
• sessionId
• agentId
• 신뢰된 인바운드 requesterSenderId

• outbound.sendPoll은 공통 poll 모델에 맞는 채널을 위한 공유 기준선입니다
• actions.handleAction("poll")은 채널별 poll 의미론 또는 추가 poll 파라미터를 위한 권장 경로입니다

​

Capability 소유권 모델

• 회사 플러그인은 보통 해당 회사의 OpenClaw 표면 전체를 소유해야 합니다
• 기능 플러그인은 보통 자신이 도입하는 기능 표면 전체를 소유해야 합니다
• 채널은 provider 동작을 임시로 재구현하지 말고 공유 core capability를 소비해야 합니다

• 번들 openai 플러그인은 OpenAI 모델-provider 동작과 OpenAI speech + realtime-voice + media-understanding + image-generation 동작을 소유합니다
• 번들 elevenlabs 플러그인은 ElevenLabs speech 동작을 소유합니다
• 번들 microsoft 플러그인은 Microsoft speech 동작을 소유합니다
• 번들 google 플러그인은 Google 모델-provider 동작과 Google media-understanding + image-generation + web-search 동작을 소유합니다
• 번들 firecrawl 플러그인은 Firecrawl web-fetch 동작을 소유합니다
• 번들 minimax, mistral, moonshot, zai 플러그인은 media-understanding 백엔드를 소유합니다
• 번들 qwen 플러그인은 Qwen 텍스트-provider 동작과 media-understanding 및 video-generation 동작을 소유합니다
• voice-call 플러그인은 기능 플러그인입니다. call transport, tool, CLI, route, Twilio media-stream bridging을 소유하지만, vendor 플러그인을 직접 import하는 대신 공유 speech, realtime-transcription, realtime-voice capability를 소비합니다

• OpenAI는 텍스트 모델, speech, image, 향후 video까지 걸쳐도 하나의 플러그인에 존재합니다
• 다른 vendor도 자신의 surface area에 대해 같은 방식으로 구성할 수 있습니다
• 채널은 어떤 vendor 플러그인이 provider를 소유하는지 신경 쓰지 않고, core가 노출하는 공유 capability 계약을 소비합니다

• plugin = 소유권 경계
• capability = 여러 플러그인이 구현하거나 소비할 수 있는 core 계약

1. core에 누락된 capability를 정의합니다
2. 이를 typed 방식으로 plugin API/runtime을 통해 노출합니다
3. 채널/기능을 그 capability에 연결합니다
4. vendor 플러그인이 구현을 등록하도록 합니다

​

Capability 계층화

• core capability 계층: 공유 orchestration, 정책, fallback, config 병합 규칙, 전달 의미론, typed 계약
• vendor plugin 계층: vendor별 API, auth, 모델 catalog, speech synthesis, image generation, 미래의 video 백엔드, usage endpoint
• channel/feature plugin 계층: Slack/Discord/voice-call 등 통합으로, core capability를 소비해 표면에 제시합니다

• core는 reply 시점 TTS 정책, fallback 순서, prefs, channel delivery를 소유합니다
• openai, elevenlabs, microsoft는 synthesis 구현을 소유합니다
• voice-call은 telephony TTS 런타임 helper를 소비합니다

​

멀티-capability 회사 플러그인 예시

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;

• 하나의 플러그인이 vendor surface를 소유합니다
• core는 여전히 capability 계약을 소유합니다
• 채널과 기능 플러그인은 vendor 코드가 아니라 api.runtime.* helper를 소비합니다
• contract test는 플러그인이 자신이 소유한다고 주장하는 capability를 등록했는지 검증할 수 있습니다

​

Capability 예시: 비디오 이해

1. core가 media-understanding 계약을 정의합니다
2. vendor 플러그인이 필요에 따라 describeImage, transcribeAudio, describeVideo를 등록합니다
3. 채널과 기능 플러그인은 vendor 코드에 직접 연결하지 않고 공유 core 동작을 소비합니다

​

계약과 강제

• 플러그인 작성자는 하나의 안정된 내부 표준을 얻게 됩니다
• core는 두 플러그인이 같은 provider id를 등록하는 식의 중복 소유권을 거부할 수 있습니다
• 시작 시 잘못된 등록에 대해 실행 가능한 진단을 표시할 수 있습니다
• contract test는 번들 플러그인 소유권을 강제하고 조용한 드리프트를 방지할 수 있습니다

1. 런타임 등록 강제 플러그인 레지스트리는 플러그인이 로드될 때 등록을 검증합니다. 예: 중복 provider id, 중복 speech provider id, 잘못된 등록은 정의되지 않은 동작 대신 플러그인 진단을 생성합니다.
2. contract test 번들 플러그인은 테스트 실행 중 contract registry에 캡처되므로, OpenClaw가 소유권을 명시적으로 검증할 수 있습니다. 오늘날 이는 모델 provider, speech provider, web search provider, 번들 등록 소유권에 사용됩니다.

​

계약에 포함되어야 할 것

• typed
• 작음
• capability별로 구체적임
• core가 소유함
• 여러 플러그인이 재사용 가능함
• vendor 지식 없이도 채널/기능이 소비 가능함

• core 안에 숨겨진 vendor별 정책
• 레지스트리를 우회하는 일회성 플러그인 탈출구
• vendor 구현에 직접 접근하는 채널 코드
• OpenClawPluginApi 또는 api.runtime의 일부가 아닌 ad hoc 런타임 객체

​

실행 모델

• 네이티브 플러그인은 tool, 네트워크 handler, hook, service를 등록할 수 있습니다
• 네이티브 플러그인 버그는 gateway를 크래시시키거나 불안정하게 만들 수 있습니다
• 악의적인 네이티브 플러그인은 OpenClaw 프로세스 내부의 임의 코드 실행과 동등합니다

• plugins.allow는 소스 provenance가 아니라 플러그인 id를 신뢰합니다.
• 번들 플러그인과 같은 id를 가진 workspace 플러그인은, 해당 workspace 플러그인이 활성화되거나 allowlist에 있으면 의도적으로 번들 사본을 가립니다.
• 이는 정상이며 로컬 개발, 패치 테스트, hotfix에 유용합니다.

​

export 경계

• 번들 플러그인 전용 helper subpath
• 공개 API가 아닌 런타임 plumbing subpath
• vendor별 convenience helper
• 구현 세부사항인 setup/onboarding helper

​

로드 파이프라인

1. 후보 플러그인 루트를 발견합니다
2. 네이티브 또는 호환 bundle manifest와 패키지 메타데이터를 읽습니다
3. 안전하지 않은 후보를 거부합니다
4. 플러그인 config를 정규화합니다 (plugins.enabled, allow, deny, entries, slots, load.paths)
5. 각 후보의 활성화 여부를 결정합니다
6. 활성화된 네이티브 모듈을 jiti를 통해 로드합니다
7. 네이티브 register(api)(또는 레거시 별칭인 activate(api)) hook을 호출하고 등록 내용을 플러그인 레지스트리에 수집합니다
8. 레지스트리를 command/runtime surface에 노출합니다

​

Manifest 우선 동작

• 플러그인 식별
• 선언된 channel/skill/config schema 또는 bundle capability 발견
• plugins.entries.<id>.config 검증
• Control UI label/placeholder 보강
• install/catalog 메타데이터 표시

​

로더가 캐시하는 것

• discovery 결과
• manifest registry 데이터
• 로드된 플러그인 레지스트리

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

​

레지스트리 모델

• 플러그인 레코드 (identity, source, origin, status, diagnostics)
• tool
• 레거시 hook 및 typed hook
• channel
• provider
• gateway RPC handler
• HTTP route
• CLI registrar
• background service
• 플러그인 소유 command

• 플러그인 모듈 -> 레지스트리 등록
• core 런타임 -> 레지스트리 소비

​

conversation binding 콜백

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

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

• status: "approved" 또는 "denied"
• decision: "allow-once", "allow-always", 또는 "deny"
• binding: 승인된 요청에 대한 resolve된 binding
• request: 원래 요청 요약, detach 힌트, sender id, conversation 메타데이터

​

Provider 런타임 훅

• manifest 메타데이터: 런타임 로드 전에 가벼운 env-auth 조회를 위한 providerAuthEnvVars, 그리고 런타임 로드 전에 onboarding/auth-choice label 및 CLI flag 메타데이터를 위한 providerAuthChoices
• config 시점 훅: catalog / 레거시 discovery 및 applyConfigDefaults
• 런타임 훅: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, shouldDeferSyntheticProfileAuth, resolveDynamicModel, prepareDynamicModel, normalizeResolvedModel, contributeResolvedModelCompat, capabilities, normalizeToolSchemas, inspectToolSchemas, resolveReasoningOutputMode, prepareExtraParams, createStreamFn, wrapStreamFn, resolveTransportTurnState, resolveWebSocketSessionPolicy, formatApiKey, refreshOAuth, buildAuthDoctorHint, matchesContextOverflowError, classifyFailoverReason, isCacheTtlEligible, buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, isBinaryThinking, supportsXHighThinking, resolveDefaultThinkingLevel, isModernModelRef, prepareRuntimeAuth, resolveUsageAuth, fetchUsageSnapshot, createEmbeddingProvider, buildReplayPolicy, sanitizeReplayHistory, validateReplayTurns, onModelSelected

​

훅 순서와 사용법

​

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);
  },
});

​

내장 예시

• Anthropic은 resolveDynamicModel, capabilities, buildAuthDoctorHint, resolveUsageAuth, fetchUsageSnapshot, isCacheTtlEligible, resolveDefaultThinkingLevel, applyConfigDefaults, isModernModelRef, wrapStreamFn을 사용합니다. 이는 Claude 4.6 forward-compat, provider-family 힌트, auth 복구 가이드, usage endpoint 통합, prompt-cache 적격성, auth 인지형 config 기본값, Claude 기본/적응형 thinking 정책, 그리고 beta header, /fast / serviceTier, context1m을 위한 Anthropic별 stream shaping을 소유하기 때문입니다.
• Anthropic의 Claude 전용 stream helper는 현재 번들 플러그인의 자체 공개 api.ts / contract-api.ts seam에 남아 있습니다. 이 패키지 surface는 한 provider의 beta-header 규칙 때문에 일반 SDK를 넓히는 대신, wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier, 그리고 더 낮은 수준의 Anthropic wrapper builder를 export합니다.
• OpenAI는 resolveDynamicModel, normalizeResolvedModel, capabilities, buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, supportsXHighThinking, isModernModelRef를 사용합니다. 이는 GPT-5.4 forward-compat, 직접 OpenAI의 openai-completions -> openai-responses 정규화, Codex 인지형 auth 힌트, Spark 억제, synthetic OpenAI 목록 row, GPT-5 thinking / live-model 정책을 소유하기 때문입니다. openai-responses-defaults stream family는 attribution header, /fast/serviceTier, text verbosity, native Codex web search, reasoning-compat payload shaping, Responses context 관리를 위한 공유 native OpenAI Responses wrapper를 소유합니다.
• OpenRouter는 catalog, resolveDynamicModel, prepareDynamicModel을 사용합니다. 이 provider는 pass-through이며 OpenClaw의 정적 catalog가 업데이트되기 전에 새 model id를 노출할 수 있기 때문입니다. 또한 provider별 request header, 라우팅 메타데이터, reasoning patch, prompt-cache 정책을 core 밖에 유지하기 위해 capabilities, wrapStreamFn, isCacheTtlEligible도 사용합니다. replay 정책은 passthrough-gemini family에서 오며, openrouter-thinking stream family는 proxy reasoning injection 및 지원되지 않는 모델 / auto 건너뛰기를 소유합니다.
• GitHub Copilot은 catalog, auth, resolveDynamicModel, capabilities, prepareRuntimeAuth, fetchUsageSnapshot을 사용합니다. 이는 provider 소유 device login, model fallback 동작, Claude transcript 특수 동작, GitHub token -> Copilot token 교환, provider 소유 usage endpoint가 필요하기 때문입니다.
• OpenAI Codex는 catalog, resolveDynamicModel, normalizeResolvedModel, refreshOAuth, augmentModelCatalog, prepareExtraParams, resolveUsageAuth, fetchUsageSnapshot을 사용합니다. 이는 여전히 core OpenAI transport 위에서 동작하지만, transport/base URL 정규화, OAuth refresh fallback 정책, 기본 transport 선택, synthetic Codex catalog row, ChatGPT usage endpoint 통합을 소유하기 때문입니다. direct OpenAI와 같은 openai-responses-defaults stream family를 공유합니다.
• Google AI Studio와 Gemini CLI OAuth는 resolveDynamicModel, buildReplayPolicy, sanitizeReplayHistory, resolveReasoningOutputMode, wrapStreamFn, isModernModelRef를 사용합니다. 이는 google-gemini replay family가 Gemini 3.1 forward-compat fallback, native Gemini replay 검증, bootstrap replay 정리, tagged reasoning-output mode, modern-model 매칭을 소유하고, google-thinking stream family가 Gemini thinking payload 정규화를 소유하기 때문입니다. Gemini CLI OAuth는 토큰 형식화, 토큰 파싱, quota endpoint 연결을 위해 formatApiKey, resolveUsageAuth, fetchUsageSnapshot도 사용합니다.
• Anthropic Vertex는 anthropic-by-model replay family를 통해 buildReplayPolicy를 사용하므로, Claude별 replay 정리가 모든 anthropic-messages transport가 아니라 Claude id에만 범위가 제한됩니다.
• Amazon Bedrock은 buildReplayPolicy, matchesContextOverflowError, classifyFailoverReason, resolveDefaultThinkingLevel을 사용합니다. 이는 Anthropic-on-Bedrock 트래픽에 대한 Bedrock별 throttle/not-ready/context-overflow 오류 분류를 소유하기 때문입니다. replay 정책은 여전히 동일한 Claude 전용 anthropic-by-model guard를 공유합니다.
• OpenRouter, Kilocode, Opencode, Opencode Go는 passthrough-gemini replay family를 통해 buildReplayPolicy를 사용합니다. 이는 OpenAI 호환 transport를 통해 Gemini 모델을 proxy하며, native Gemini replay 검증 또는 bootstrap 재작성 없이도 Gemini thought-signature 정리가 필요하기 때문입니다.
• MiniMax는 hybrid-anthropic-openai replay family를 통해 buildReplayPolicy를 사용합니다. 이는 한 provider가 Anthropic-message와 OpenAI 호환 의미론을 모두 소유하기 때문입니다. Anthropic 쪽에서는 Claude 전용 thinking-block 제거를 유지하면서 reasoning 출력 모드를 native로 다시 override하고, minimax-fast-mode stream family는 공유 stream 경로에서 fast-mode 모델 재작성을 소유합니다.
• Moonshot은 catalog, wrapStreamFn을 사용합니다. 여전히 공유 OpenAI transport를 사용하지만 provider 소유 thinking payload 정규화가 필요하기 때문입니다. moonshot-thinking stream family는 config와 /think 상태를 native binary thinking payload에 매핑합니다.
• Kilocode는 catalog, capabilities, wrapStreamFn, isCacheTtlEligible를 사용합니다. provider 소유 request header, reasoning payload 정규화, Gemini transcript 힌트, Anthropic cache-TTL 게이팅이 필요하기 때문입니다. kilocode-thinking stream family는 공유 proxy stream 경로에서 Kilo thinking injection을 유지하면서, 명시적 reasoning payload를 지원하지 않는 kilo/auto와 기타 proxy model id는 건너뜁니다.
• Z.AI는 resolveDynamicModel, prepareExtraParams, wrapStreamFn, isCacheTtlEligible, isBinaryThinking, isModernModelRef, resolveUsageAuth, fetchUsageSnapshot을 사용합니다. 이는 GLM-5 fallback, tool_stream 기본값, binary thinking UX, modern-model 매칭, 그리고 usage auth + quota fetching을 모두 소유하기 때문입니다. tool-stream-default-on stream family는 기본 활성화된 tool_stream wrapper를 provider별 수동 glue 밖에 유지합니다.
• xAI는 normalizeResolvedModel, normalizeTransport, contributeResolvedModelCompat, prepareExtraParams, wrapStreamFn, resolveSyntheticAuth, resolveDynamicModel, isModernModelRef를 사용합니다. 이는 native xAI Responses transport 정규화, Grok fast-mode alias 재작성, 기본 tool_stream, strict-tool / reasoning-payload 정리, 플러그인 소유 tool용 fallback auth 재사용, forward-compat Grok model resolve, xAI tool-schema profile, 미지원 schema keyword, native web_search, HTML entity tool-call argument decoding 같은 provider 소유 compat patch를 소유하기 때문입니다.
• Mistral, OpenCode Zen, OpenCode Go는 transcript/tooling 특수 동작을 core 밖에 두기 위해 capabilities만 사용합니다.
• byteplus, cloudflare-ai-gateway, huggingface, kimi-coding, nvidia, qianfan, synthetic, together, venice, vercel-ai-gateway, volcengine 같은 catalog 전용 번들 provider는 catalog만 사용합니다.
• Qwen은 텍스트 provider용 catalog와, multimodal surface를 위한 공유 media-understanding 및 video-generation 등록을 사용합니다.
• MiniMax와 Xiaomi는 추론은 여전히 공유 transport를 통해 실행되더라도 /usage 동작이 플러그인 소유이기 때문에 catalog와 usage 훅을 사용합니다.

​

런타임 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는 파일/음성 노트 surface를 위한 일반 core TTS output payload를 반환합니다.
• core messages.tts config와 provider 선택을 사용합니다.
• PCM 오디오 버퍼 + 샘플 레이트를 반환합니다. 플러그인은 provider에 맞게 리샘플링/인코딩해야 합니다.
• listVoices는 provider별로 선택 사항입니다. vendor 소유 voice picker 또는 setup flow에 사용하세요.
• voice 목록은 locale, gender, personality tag 같은 더 풍부한 메타데이터를 포함할 수 있어 provider 인지형 picker에 활용할 수 있습니다.
• 현재 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 정책, fallback, reply 전달은 core에 유지하세요.
• vendor 소유 synthesis 동작에는 speech provider를 사용하세요.
• 레거시 Microsoft edge 입력은 microsoft provider id로 정규화됩니다.
• 선호되는 소유권 모델은 회사 지향적입니다. OpenClaw가 이러한 capability 계약을 추가해 갈수록 하나의 vendor 플러그인이 텍스트, speech, image, 향후 미디어 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 연결은 core에 유지하세요.
• vendor 동작은 provider 플러그인에 유지하세요.
• 점진적 확장은 typed 상태를 유지해야 합니다: 새로운 선택적 메서드, 새로운 선택적 결과 필드, 새로운 선택적 capability.
• 비디오 생성도 이미 같은 패턴을 따릅니다.
  • core가 capability 계약과 런타임 helper를 소유합니다
  • vendor 플러그인이 api.registerVideoGenerationProvider(...)를 등록합니다
  • 기능/채널 플러그인이 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.*는 image/audio/video 이해를 위한 선호 공유 surface입니다.
• core media-understanding 오디오 config (tools.media.audio)와 provider fallback 순서를 사용합니다.
• 전사 출력이 생성되지 않으면 { 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은 지속적인 session 변경이 아니라 run별 override입니다.
• OpenClaw는 신뢰된 caller에 대해서만 이러한 override 필드를 허용합니다.
• 플러그인 소유 fallback 실행의 경우 운영자는 plugins.entries.<id>.subagent.allowModelOverride: true로 opt-in해야 합니다.
• 신뢰된 플러그인을 특정 canonical provider/model 대상으로 제한하려면 plugins.entries.<id>.subagent.allowedModels를 사용하고, 모든 대상을 명시적으로 허용하려면 "*"를 사용하세요.
• 신뢰되지 않은 플러그인의 subagent 실행도 동작하지만, override 요청은 조용히 fallback되지 않고 거부됩니다.

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 선택, credential resolve, 공유 request 의미론은 core에 유지하세요.
• vendor별 검색 transport에는 웹 검색 provider를 사용하세요.
• api.runtime.webSearch.*는 agent tool wrapper에 의존하지 않고 검색 동작이 필요한 기능/채널 플러그인을 위한 선호 공유 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(...): 설정된 image-generation provider 체인을 사용해 이미지를 생성합니다.
• 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 서버 아래의 route 경로
• auth: 필수. 일반 gateway auth가 필요하면 "gateway"를, 플러그인 관리 auth/webhook 검증이면 "plugin"을 사용하세요.
• match: 선택 사항. "exact"(기본값) 또는 "prefix".
• replaceExisting: 선택 사항. 같은 플러그인이 자신의 기존 route 등록을 대체할 수 있게 합니다.
• handler: route가 request를 처리했으면 true를 반환합니다.

• api.registerHttpHandler(...)는 제거되었으며 플러그인 로드 오류를 발생시킵니다. 대신 api.registerHttpRoute(...)를 사용하세요.
• 플러그인 route는 반드시 auth를 명시적으로 선언해야 합니다.
• 정확히 같은 path + match 충돌은 replaceExisting: true가 아닌 한 거부되며, 한 플러그인이 다른 플러그인의 route를 대체할 수 없습니다.
• 서로 다른 auth 수준의 겹치는 route는 거부됩니다. exact/prefix fallthrough 체인은 같은 auth 수준 안에서만 유지하세요.
• auth: "plugin" route는 운영자 런타임 scope를 자동으로 받지 않습니다. 이는 특권 있는 Gateway helper 호출이 아니라 플러그인 관리 webhook/서명 검증용입니다.
• auth: "gateway" route는 Gateway request runtime scope 안에서 실행되지만, 그 scope는 의도적으로 보수적입니다.
  • 공유 비밀 bearer auth (gateway.auth.mode = "token" / "password")는 호출자가 x-openclaw-scopes를 보내더라도 플러그인 route 런타임 scope를 operator.write에 고정합니다
  • 신뢰된 identity-bearing HTTP 모드(예: trusted-proxy 또는 사설 ingress의 gateway.auth.mode = "none")는 헤더가 명시적으로 존재할 때만 x-openclaw-scopes를 존중합니다
  • 그러한 identity-bearing 플러그인 route 요청에서 x-openclaw-scopes가 없으면, 런타임 scope는 operator.write로 fallback됩니다
• 실용적인 규칙: gateway-auth 플러그인 route를 암묵적인 admin surface로 가정하지 마세요. route에 admin 전용 동작이 필요하다면 identity-bearing auth 모드를 요구하고, 명시적 x-openclaw-scopes header 계약을 문서화하세요.

​

Plugin SDK import 경로

• 플러그인 등록 primitive에는 openclaw/plugin-sdk/plugin-entry
• 일반 공유 plugin 대상 계약에는 openclaw/plugin-sdk/core
• 루트 openclaw.json Zod schema export (OpenClawSchema)에는 openclaw/plugin-sdk/config-schema
• openclaw/plugin-sdk/channel-setup, openclaw/plugin-sdk/setup-runtime, openclaw/plugin-sdk/setup-adapter-runtime, openclaw/plugin-sdk/setup-tools, openclaw/plugin-sdk/channel-pairing, openclaw/plugin-sdk/channel-contract, openclaw/plugin-sdk/channel-feedback, openclaw/plugin-sdk/channel-inbound, openclaw/plugin-sdk/channel-lifecycle, openclaw/plugin-sdk/channel-reply-pipeline, openclaw/plugin-sdk/command-auth, openclaw/plugin-sdk/secret-input, openclaw/plugin-sdk/webhook-ingress 같은 안정적인 채널 primitive는 공유 setup/auth/reply/webhook wiring용입니다. channel-inbound는 debounce, mention 매칭, envelope formatting, inbound envelope 컨텍스트 helper를 위한 공유 홈입니다. channel-setup은 좁은 optional-install setup seam입니다. setup-runtime은 setupEntry / deferred startup에 사용되는 런타임 안전 setup surface이며, import-safe setup patch adapter를 포함합니다. setup-adapter-runtime은 env 인지형 account-setup adapter seam입니다. setup-tools는 작은 CLI/archive/docs helper seam입니다 (formatCliCommand, detectBinary, extractArchive, resolveBrewExecutable, formatDocsLink, CONFIG_DIR).
• openclaw/plugin-sdk/channel-config-helpers, openclaw/plugin-sdk/allow-from, openclaw/plugin-sdk/channel-config-schema, openclaw/plugin-sdk/telegram-command-config, openclaw/plugin-sdk/channel-policy, openclaw/plugin-sdk/approval-runtime, openclaw/plugin-sdk/config-runtime, openclaw/plugin-sdk/infra-runtime, openclaw/plugin-sdk/agent-runtime, openclaw/plugin-sdk/lazy-runtime, openclaw/plugin-sdk/reply-history, openclaw/plugin-sdk/routing, openclaw/plugin-sdk/status-helpers, openclaw/plugin-sdk/text-runtime, openclaw/plugin-sdk/runtime-store, openclaw/plugin-sdk/directory-runtime 같은 도메인 subpath는 공유 런타임/config helper용입니다. telegram-command-config는 Telegram 커스텀 command 정규화/검증을 위한 좁은 공개 seam이며, 번들 Telegram 계약 surface를 일시적으로 사용할 수 없더라도 계속 제공합니다. text-runtime은 assistant-visible-text 제거, markdown render/chunking helper, redaction helper, directive-tag helper, safe-text 유틸리티를 포함하는 공유 text/markdown/logging seam입니다.
• approval 전용 채널 seam은 하나의 approvalCapability 계약을 플러그인에 두는 방식을 우선해야 합니다. 그러면 core는 관련 없는 플러그인 필드에 approval 동작을 섞는 대신, 그 하나의 capability를 통해 approval auth, delivery, render, native-routing 동작을 읽을 수 있습니다.
• openclaw/plugin-sdk/channel-runtime은 deprecated되었으며 오래된 플러그인을 위한 호환성 shim으로만 남아 있습니다. 새 코드는 더 좁은 일반 primitive를 import해야 하며, repo 코드도 shim의 새 import를 추가해서는 안 됩니다.
• 번들 extension 내부는 비공개로 유지됩니다. 외부 플러그인은 openclaw/plugin-sdk/* subpath만 사용해야 합니다. OpenClaw core/test 코드는 index.js, api.js, runtime-api.js, setup-entry.js, login-qr-api.js 같은 플러그인 패키지 루트의 공개 entry point와, 필요한 경우 일부 좁은 파일을 사용할 수 있습니다. core나 다른 extension에서 플러그인 패키지의 src/*를 import하지 마세요.
• repo entry point 분리: <plugin-package-root>/api.js는 helper/types barrel, <plugin-package-root>/runtime-api.js는 런타임 전용 barrel, <plugin-package-root>/index.js는 번들 플러그인 entry, <plugin-package-root>/setup-entry.js는 setup 플러그인 entry입니다.
• 현재 번들 provider 예시:
  • Anthropic은 wrapAnthropicProviderStream, beta-header helper, service_tier 파싱 같은 Claude stream helper를 위해 api.js / contract-api.js를 사용합니다.
  • OpenAI는 provider builder, default-model helper, realtime provider builder를 위해 api.js를 사용합니다.
  • OpenRouter는 provider builder와 onboarding/config helper를 위해 api.js를 사용하며, register.runtime.js는 repo 로컬 사용을 위해 일반 plugin-sdk/provider-stream helper를 재export할 수 있습니다.
• facade로 로드되는 공개 entry point는 활성 런타임 config snapshot이 있으면 이를 우선 사용하고, OpenClaw가 아직 런타임 snapshot을 제공하지 않을 때는 디스크의 resolve된 config 파일로 fallback합니다.
• 일반 공유 primitive는 여전히 선호되는 공개 SDK 계약입니다. 소수의 예약된 호환성용 번들 채널 브랜드 helper seam은 여전히 존재합니다. 이를 새로운 서드파티 import 대상이 아니라, 번들 유지보수/호환성 seam으로 취급하세요. 새로운 교차 채널 계약은 계속해서 일반 plugin-sdk/* subpath 또는 플러그인 로컬 api.js / runtime-api.js barrel에 추가되어야 합니다.

• 새 코드에서는 루트 openclaw/plugin-sdk barrel을 피하세요.
• 더 좁고 안정적인 primitive를 우선하세요. 더 새로운 setup/pairing/reply/ feedback/contract/inbound/threading/command/secret-input/webhook/infra/ allowlist/status/message-tool subpath는 새로운 번들 및 외부 플러그인 작업을 위한 의도된 계약입니다. target 파싱/매칭은 openclaw/plugin-sdk/channel-targets에 있어야 합니다. message action gate와 reaction message-id helper는 openclaw/plugin-sdk/channel-actions에 있어야 합니다.
• 번들 extension 전용 helper barrel은 기본적으로 안정적이지 않습니다. helper가 번들 extension에만 필요하다면, 이를 openclaw/plugin-sdk/<extension>로 승격하는 대신 extension의 로컬 api.js 또는 runtime-api.js seam 뒤에 두세요.
• 새로운 공유 helper seam은 채널 브랜드가 아니라 일반적이어야 합니다. 공유 target 파싱은 openclaw/plugin-sdk/channel-targets에 두고, 채널별 내부는 소유 플러그인의 로컬 api.js 또는 runtime-api.js seam 뒤에 유지하세요.
• image-generation, media-understanding, speech 같은 capability별 subpath는 오늘날 번들/네이티브 플러그인이 사용하기 때문에 존재합니다. 이들의 존재 자체가 export된 모든 helper가 장기적으로 고정된 외부 계약임을 의미하지는 않습니다.

​

Message tool schema

• 버튼 그리드 스타일 payload용 createMessageToolButtonsSchema()
• 구조화된 card payload용 createMessageToolCardSchema()

​

채널 target resolve

• messaging.inferTargetChatType({ to })는 정규화된 target이 directory 조회 전에 direct, group, channel 중 무엇으로 취급되어야 하는지 결정합니다.
• messaging.targetResolver.looksLikeId(raw, normalized)는 core에 입력이 directory 검색 대신 id 형태의 resolve로 바로 넘어가야 하는지를 알려줍니다.
• messaging.targetResolver.resolveTarget(...)는 정규화 후 또는 directory miss 후 최종 provider 소유 resolve가 필요할 때 플러그인 fallback입니다.
• messaging.resolveOutboundSessionRoute(...)는 target resolve 후 provider별 session route 구성을 소유합니다.

• peers/groups를 검색하기 전에 이루어져야 하는 카테고리 결정에는 inferTargetChatType 사용
• “이를 명시적/native target id로 취급할지” 검사에는 looksLikeId 사용
• provider별 정규화 fallback에는 resolveTarget을 사용하고, 광범위한 directory 검색에는 사용하지 않음
• chat id, thread id, JID, handle, room id 같은 provider-native id는 일반 SDK field가 아니라 target 값이나 provider별 파라미터 안에 유지

​

Config 기반 directory

• allowlist 기반 DM peer
• 설정된 channel/group map
• account 범위의 정적 directory fallback

• 쿼리 필터링
• limit 적용
• dedupe/정규화 helper
• ChannelDirectoryEntry[] 구성

​

Provider catalog

• 하나의 provider entry에 대한 { provider }
• 여러 provider entry에 대한 { providers }

• simple: 일반 API 키 또는 env 기반 provider
• profile: auth profile이 존재할 때 나타나는 provider
• paired: 여러 관련 provider entry를 합성하는 provider
• late: 다른 암시적 provider 이후의 마지막 단계

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

​

읽기 전용 채널 검사

• resolveAccount(...)는 런타임 경로입니다. credential이 완전히 materialize되었다고 가정할 수 있으며, 필요한 secret이 없으면 빠르게 실패해도 됩니다.
• openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve, doctor/config repair flow 같은 읽기 전용 command 경로는 설정 상태를 설명하기 위해 런타임 credential을 materialize할 필요가 없어야 합니다.

• 설명용 account 상태만 반환합니다.
• enabled와 configured를 유지합니다.
• 관련이 있다면 credential source/status field를 포함합니다. 예:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• 읽기 전용 가용성을 보고하기 위해 raw token 값을 반환할 필요는 없습니다. 상태 스타일 command에는 tokenStatus: "available"(및 일치하는 source field)면 충분합니다.
• credential이 SecretRef로 구성되었지만 현재 command 경로에서는 사용할 수 없을 때는 configured_unavailable을 사용하세요.

​

패키지 pack

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

• channel 등록 자체
• gateway가 리슨하기 전에 사용 가능해야 하는 모든 HTTP route
• 같은 시점에 존재해야 하는 모든 gateway method, tool, service

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

채널 catalog 메타데이터

{
  "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": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: 더 풍부한 catalog/status surface를 위한 보조 label
• docsLabel: docs 링크 텍스트 override
• preferOver: 이 catalog entry가 앞서야 하는 더 낮은 우선순위의 plugin/channel id
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: selection-surface 복사 제어
• markdownCapable: outbound formatting 결정에서 이 채널이 markdown 가능함을 표시
• showConfigured: false로 설정 시 configured-channel 목록 surface에서 채널을 숨김
• quickstartAllowFrom: 채널을 표준 quickstart allowFrom flow에 opt-in
• forceAccountBinding: account가 하나뿐이어도 명시적 account binding을 요구
• preferSessionLookupForAnnounceTarget: announce target resolve 시 session 조회를 우선

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

​

컨텍스트 엔진 플러그인

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 }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import { 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 }) {
      return { messages, estimatedTokens: 0 };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

새 capability 추가

1. core 계약 정의 core가 소유해야 하는 공유 동작을 결정합니다. 정책, fallback, config 병합, 라이프사이클, 채널 대상 의미론, 런타임 helper 형태가 여기에 포함됩니다.
2. typed 플러그인 등록/런타임 surface 추가 OpenClawPluginApi 및/또는 api.runtime를 가장 작지만 유용한 typed capability surface로 확장합니다.
3. core + 채널/기능 소비자 연결 채널과 기능 플러그인은 vendor 구현을 직접 import하지 말고 core를 통해 새 capability를 소비해야 합니다.
4. vendor 구현 등록 이후 vendor 플러그인이 그 capability에 백엔드를 등록합니다.
5. contract 커버리지 추가 시간이 지나도 소유권과 등록 형태가 명시적으로 유지되도록 테스트를 추가합니다.

​

Capability 체크리스트

• src/<capability>/types.ts의 core 계약 타입
• src/<capability>/runtime.ts의 core runner/runtime helper
• src/plugins/types.ts의 plugin API 등록 surface
• src/plugins/registry.ts의 plugin registry wiring
• 기능/채널 플러그인이 이를 소비해야 한다면 src/plugins/runtime/*의 plugin 런타임 노출
• src/test-utils/plugin-registration.ts의 capture/test helper
• src/plugins/contracts/registry.ts의 소유권/contract assertion
• docs/의 운영자/플러그인 문서

​

Capability 템플릿

// 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용 공유 런타임 helper
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

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

• core가 capability 계약 + orchestration을 소유합니다
• vendor 플러그인이 vendor 구현을 소유합니다
• 기능/채널 플러그인이 런타임 helper를 소비합니다
• contract test가 소유권을 명시적으로 유지합니다