​

Plugin 내부 구조

​

공개 기능 모델

​

외부 호환성 입장

• 기존 외부 플러그인: 훅 기반 통합이 계속 동작하도록 유지하고, 이를 호환성 기준선으로 취급합니다
• 새 번들/기본 플러그인: 벤더별 직접 연동이나 새로운 hook-only 설계보다 명시적인 기능 등록을 우선합니다
• 기능 등록을 도입하는 외부 플러그인: 허용되지만, 문서에서 계약이 안정적이라고 명시적으로 표시하지 않는 한 기능별 헬퍼 표면은 계속 발전하는 것으로 간주합니다

• 기능 등록 API가 의도된 방향입니다
• 전환 기간 동안 레거시 훅은 외부 플러그인에 대해 가장 안전한 비호환성 없는 경로로 남습니다
• 내보낸 헬퍼 하위 경로가 모두 같은 것은 아닙니다. 우연히 노출된 헬퍼 export가 아니라, 문서화된 좁은 계약을 우선하세요

​

Plugin 형태

• plain-capability — 정확히 하나의 기능 유형만 등록합니다(예: mistral 같은 provider-only 플러그인)
• hybrid-capability — 여러 기능 유형을 등록합니다(예: openai는 텍스트 추론, 음성, 미디어 이해, 이미지 생성을 담당함)
• hook-only — 기능, 도구, 명령, 서비스 없이 훅만 등록합니다(타입드 훅 또는 커스텀 훅)
• non-capability — 기능 없이 도구, 명령, 서비스 또는 라우트를 등록합니다

​

레거시 훅

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

​

호환성 신호

​

아키텍처 개요

1. 매니페스트 + 탐색 OpenClaw는 구성된 경로, 워크스페이스 루트, 전역 확장 루트, 번들 확장에서 후보 플러그인을 찾습니다. 탐색은 먼저 기본 openclaw.plugin.json 매니페스트와 지원되는 번들 매니페스트를 읽습니다.
2. 활성화 + 검증 코어는 탐지된 플러그인이 활성화, 비활성화, 차단되었는지 또는 메모리와 같은 독점 슬롯에 선택되었는지를 결정합니다.
3. 런타임 로드 기본 OpenClaw Plugin은 jiti를 통해 프로세스 내에서 로드되고, 중앙 레지스트리에 기능을 등록합니다. 호환되는 번들은 런타임 코드를 import하지 않고 레지스트리 레코드로 정규화됩니다.
4. 표면 사용 OpenClaw의 나머지 부분은 레지스트리를 읽어 도구, 채널, 프로바이더 설정, 훅, HTTP 라우트, CLI 명령, 서비스를 노출합니다.

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

• 탐색 + 설정 검증은 plugin 코드를 실행하지 않고 매니페스트/스키마 메타데이터만으로 동작해야 합니다
• 기본 런타임 동작은 plugin 모듈의 register(api) 경로에서 나옵니다

​

채널 Plugin과 공유 message 도구

• 코어는 공유 message 도구 호스트, 프롬프트 연결, 세션/스레드 기록 관리, 실행 디스패치를 담당합니다
• 채널 Plugin은 범위가 지정된 작업 탐색, 기능 탐색, 채널별 스키마 조각을 담당합니다
• 채널 Plugin은 대화 ID가 스레드 ID를 인코딩하거나 상위 대화에서 상속되는 방식처럼, 프로바이더별 세션 대화 문법을 담당합니다
• 채널 Plugin은 자신의 action adapter를 통해 최종 작업을 실행합니다

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

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

​

기능 소유권 모델

• 회사 플러그인은 보통 그 회사의 OpenClaw 관련 표면 전체를 소유해야 합니다
• 기능 플러그인은 보통 자신이 도입하는 전체 기능 표면을 소유해야 합니다
• 채널은 프로바이더 동작을 그때그때 다시 구현하는 대신 공유 코어 기능을 사용해야 합니다

• 번들된 openai 플러그인은 OpenAI 모델 프로바이더 동작과 OpenAI 음성 + 실시간 음성 + 미디어 이해 + 이미지 생성 동작을 소유합니다
• 번들된 elevenlabs 플러그인은 ElevenLabs 음성 동작을 소유합니다
• 번들된 microsoft 플러그인은 Microsoft 음성 동작을 소유합니다
• 번들된 google 플러그인은 Google 모델 프로바이더 동작과 Google 미디어 이해 + 이미지 생성 + 웹 검색 동작을 소유합니다
• 번들된 firecrawl 플러그인은 Firecrawl 웹 가져오기 동작을 소유합니다
• 번들된 minimax, mistral, moonshot, zai 플러그인은 각각의 미디어 이해 백엔드를 소유합니다
• 번들된 qwen 플러그인은 Qwen 텍스트 프로바이더 동작과 미디어 이해 및 비디오 생성 동작을 소유합니다
• voice-call 플러그인은 기능 플러그인입니다. 통화 전송, 도구, CLI, 라우트, Twilio 미디어 스트림 브리징을 소유하지만, 벤더 플러그인을 직접 import하는 대신 공유 음성 기능과 실시간 전사 및 실시간 음성 기능을 사용합니다

• OpenAI는 텍스트 모델, 음성, 이미지, 미래의 비디오까지 아우르더라도 하나의 플러그인에 존재합니다
• 다른 벤더도 자체 표면 영역에 대해 동일하게 할 수 있습니다
• 채널은 어느 벤더 플러그인이 프로바이더를 소유하는지 신경 쓰지 않고, 코어가 노출하는 공유 기능 계약을 사용합니다

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

1. 코어에서 누락된 기능을 정의합니다
2. 타입이 지정된 방식으로 plugin API/런타임을 통해 이를 노출합니다
3. 채널/기능을 그 기능에 맞게 연결합니다
4. 벤더 플러그인이 구현을 등록하도록 합니다

​

기능 계층화

• 코어 기능 계층: 공유 오케스트레이션, 정책, 폴백, 설정 병합 규칙, 전달 의미론, 타입 계약
• 벤더 플러그인 계층: 벤더별 API, 인증, 모델 카탈로그, 음성 합성, 이미지 생성, 미래의 비디오 백엔드, 사용량 엔드포인트
• 채널/기능 플러그인 계층: 코어 기능을 사용하여 이를 표면에 제공하는 Slack/Discord/voice-call 등의 통합

• 코어는 응답 시점 TTS 정책, 폴백 순서, 기본 설정, 채널 전달을 소유합니다
• openai, elevenlabs, microsoft는 합성 구현을 소유합니다
• voice-call은 전화 통신 TTS 런타임 헬퍼를 사용합니다

​

다중 기능 회사 플러그인 예시

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;

• 하나의 플러그인이 벤더 표면을 소유합니다
• 코어는 여전히 기능 계약을 소유합니다
• 채널과 기능 플러그인은 벤더 코드가 아니라 api.runtime.* 헬퍼를 사용합니다
• 계약 테스트는 플러그인이 자신이 소유한다고 주장하는 기능을 등록했는지 검증할 수 있습니다

​

기능 예시: 비디오 이해

1. 코어가 미디어 이해 계약을 정의합니다
2. 벤더 플러그인은 해당하는 경우 describeImage, transcribeAudio, describeVideo를 등록합니다
3. 채널과 기능 플러그인은 벤더 코드에 직접 연결하는 대신 공유 코어 동작을 사용합니다

​

계약 및 적용

• 플러그인 작성자는 하나의 안정적인 내부 표준을 갖게 됩니다
• 코어는 두 플러그인이 동일한 프로바이더 ID를 등록하는 것과 같은 중복 소유를 거부할 수 있습니다
• 시작 시 잘못된 등록에 대해 실행 가능한 진단을 표시할 수 있습니다
• 계약 테스트는 번들 플러그인 소유권을 강제하고 조용한 드리프트를 방지할 수 있습니다

1. 런타임 등록 적용 플러그인 레지스트리는 플러그인이 로드될 때 등록을 검증합니다. 예: 중복 프로바이더 ID, 중복 음성 프로바이더 ID, 잘못된 등록은 정의되지 않은 동작 대신 플러그인 진단을 생성합니다.
2. 계약 테스트 번들 플러그인은 테스트 실행 중 계약 레지스트리에 캡처되므로 OpenClaw는 소유권을 명시적으로 검증할 수 있습니다. 현재 이는 모델 프로바이더, 음성 프로바이더, 웹 검색 프로바이더, 번들 등록 소유권에 사용됩니다.

​

계약에 포함되어야 하는 것

• 타입이 지정되어 있음
• 작음
• 기능별로 구체적임
• 코어가 소유함
• 여러 플러그인이 재사용 가능함
• 채널/기능이 벤더 지식 없이 사용할 수 있음

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

​

실행 모델

• 기본 플러그인은 도구, 네트워크 핸들러, 훅, 서비스를 등록할 수 있습니다
• 기본 플러그인 버그는 gateway를 크래시시키거나 불안정하게 만들 수 있습니다
• 악의적인 기본 플러그인은 OpenClaw 프로세스 내부에서의 임의 코드 실행과 동일합니다

• plugins.allow는 소스 출처가 아니라 plugin id를 신뢰합니다.
• 번들 플러그인과 동일한 ID를 가진 워크스페이스 플러그인은 그 워크스페이스 플러그인이 활성화/허용 목록에 있으면 의도적으로 번들 사본을 가립니다.
• 이는 정상적이며 로컬 개발, 패치 테스트, 핫픽스에 유용합니다.

​

export 경계

• 번들 플러그인 전용 헬퍼 하위 경로
• 공개 API로 의도되지 않은 런타임 플러밍 하위 경로
• 벤더별 편의 헬퍼
• 구현 세부 사항인 설정/온보딩 헬퍼

​

로드 파이프라인

1. 후보 플러그인 루트를 탐색합니다
2. 기본 또는 호환 가능한 번들 매니페스트와 패키지 메타데이터를 읽습니다
3. 안전하지 않은 후보를 거부합니다
4. plugin 설정을 정규화합니다 (plugins.enabled, allow, deny, entries, slots, load.paths)
5. 각 후보의 활성화 여부를 결정합니다
6. 활성화된 기본 모듈을 jiti로 로드합니다
7. 기본 register(api)(또는 레거시 별칭인 activate(api)) 훅을 호출하고 플러그인 레지스트리에 등록 항목을 수집합니다
8. 명령/런타임 표면에 레지스트리를 노출합니다

​

매니페스트 우선 동작

• 플러그인 식별
• 선언된 채널/Skills/설정 스키마 또는 번들 기능 탐색
• plugins.entries.<id>.config 검증
• Control UI 라벨/플레이스홀더 보강
• 설치/카탈로그 메타데이터 표시
• plugin 런타임을 로드하지 않고도 가벼운 활성화 및 설정 descriptor 유지

• CLI 로드는 요청된 기본 명령을 소유한 플러그인으로 좁혀집니다
• 채널 설정/플러그인 해결은 요청된 채널 ID를 소유한 플러그인으로 좁혀집니다
• 명시적 프로바이더 설정/런타임 해결은 요청된 프로바이더 ID를 소유한 플러그인으로 좁혀집니다

​

로더가 캐시하는 것

• 탐색 결과
• 매니페스트 레지스트리 데이터
• 로드된 플러그인 레지스트리

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

​

레지스트리 모델

• 플러그인 레코드(정체성, 소스, 출처, 상태, 진단)
• 도구
• 레거시 훅 및 타입 지정 훅
• 채널
• 프로바이더
• Gateway RPC 핸들러
• HTTP 라우트
• CLI 등록기
• 백그라운드 서비스
• 플러그인 소유 명령

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

​

대화 바인딩 콜백

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: 원본 요청 요약, 분리 힌트, 발신자 ID 및 대화 메타데이터

​

프로바이더 런타임 훅

• 매니페스트 메타데이터: 런타임 로드 전에 가벼운 프로바이더 환경 인증 조회를 위한 providerAuthEnvVars, 인증을 공유하는 프로바이더 변형을 위한 providerAuthAliases, 런타임 로드 전에 가벼운 채널 환경/설정 조회를 위한 channelEnvVars, 그리고 런타임 로드 전에 가벼운 온보딩/인증 선택 라벨 및 CLI 플래그 메타데이터를 위한 providerAuthChoices
• 설정 시점 훅: catalog / 레거시 discovery 및 applyConfigDefaults
• 런타임 훅: normalizeModelId, normalizeTransport, normalizeConfig, applyNativeStreamingUsageCompat, resolveConfigApiKey, resolveSyntheticAuth, resolveExternalAuthProfiles, 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

​

훅 순서 및 사용법

​

프로바이더 예시

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, 프로바이더 계열 힌트, 인증 복구 가이드, 사용량 엔드포인트 통합, 프롬프트 캐시 적격성, 인증 인지 설정 기본값, Claude 기본/적응형 thinking 정책, 베타 헤더, /fast / serviceTier, context1m을 위한 Anthropic 전용 스트림 형태 조정을 소유하기 때문입니다.
• Anthropic의 Claude 전용 스트림 헬퍼는 현재 번들 플러그인의 자체 공개 api.ts / contract-api.ts seam에 남아 있습니다. 해당 패키지 표면은 하나의 프로바이더 베타 헤더 규칙을 기준으로 일반 SDK를 넓히는 대신 wrapAnthropicProviderStream, resolveAnthropicBetas, resolveAnthropicFastMode, resolveAnthropicServiceTier, 그리고 하위 수준 Anthropic 래퍼 빌더를 export합니다.
• OpenAI는 resolveDynamicModel, normalizeResolvedModel, capabilities와 함께 buildMissingAuthMessage, suppressBuiltInModel, augmentModelCatalog, supportsXHighThinking, isModernModelRef를 사용합니다. 이는 GPT-5.4 forward-compat, 직접 OpenAI openai-completions -> openai-responses 정규화, Codex 인지 인증 힌트, Spark 억제, 합성 OpenAI 목록 행, GPT-5 thinking / 라이브 모델 정책을 소유하기 때문입니다. openai-responses-defaults 스트림 계열은 attribution 헤더, /fast/serviceTier, 텍스트 verbosity, 기본 Codex 웹 검색, reasoning-compat 페이로드 형태 조정, Responses 컨텍스트 관리를 위한 공유 기본 OpenAI Responses 래퍼를 소유합니다.
• OpenRouter는 catalog와 함께 resolveDynamicModel, prepareDynamicModel을 사용합니다. 이 프로바이더는 패스스루이므로 OpenClaw의 정적 카탈로그가 업데이트되기 전에 새 모델 ID를 노출할 수 있기 때문입니다. 또한 프로바이더별 요청 헤더, 라우팅 메타데이터, reasoning 패치, 프롬프트 캐시 정책이 코어로 들어오지 않도록 capabilities, wrapStreamFn, isCacheTtlEligible도 사용합니다. 리플레이 정책은 passthrough-gemini 계열에서 오며, openrouter-thinking 스트림 계열은 프록시 reasoning 주입과 지원되지 않는 모델 / auto 건너뛰기를 소유합니다.
• GitHub Copilot은 catalog, auth, resolveDynamicModel, capabilities와 함께 prepareRuntimeAuth, fetchUsageSnapshot을 사용합니다. 이는 프로바이더 소유 장치 로그인, 모델 폴백 동작, Claude 전사 특수 동작, GitHub 토큰 -> Copilot 토큰 교환, 프로바이더 소유 사용량 엔드포인트가 필요하기 때문입니다.
• OpenAI Codex는 catalog, resolveDynamicModel, normalizeResolvedModel, refreshOAuth, augmentModelCatalog와 함께 prepareExtraParams, resolveUsageAuth, fetchUsageSnapshot을 사용합니다. 이는 여전히 코어 OpenAI 전송에서 실행되지만 전송/base URL 정규화, OAuth 리프레시 폴백 정책, 기본 전송 선택, 합성 Codex 카탈로그 행, ChatGPT 사용량 엔드포인트 통합을 소유하기 때문입니다. 이 프로바이더는 직접 OpenAI와 동일한 openai-responses-defaults 스트림 계열을 공유합니다.
• Google AI Studio와 Gemini CLI OAuth는 resolveDynamicModel, buildReplayPolicy, sanitizeReplayHistory, resolveReasoningOutputMode, wrapStreamFn, isModernModelRef를 사용합니다. 이는 google-gemini 리플레이 계열이 Gemini 3.1 forward-compat 폴백, 기본 Gemini 리플레이 검증, bootstrap 리플레이 정리, 태그 기반 reasoning-output 모드, 최신 모델 매칭을 소유하고, google-thinking 스트림 계열이 Gemini thinking 페이로드 정규화를 소유하기 때문입니다. Gemini CLI OAuth는 토큰 형식화, 토큰 파싱, 할당량 엔드포인트 연결을 위해 formatApiKey, resolveUsageAuth, fetchUsageSnapshot도 사용합니다.
• Anthropic Vertex는 anthropic-by-model 리플레이 계열을 통해 buildReplayPolicy를 사용하므로 Claude 전용 리플레이 정리가 모든 anthropic-messages 전송이 아니라 Claude ID에만 범위가 제한됩니다.
• Amazon Bedrock은 buildReplayPolicy, matchesContextOverflowError, classifyFailoverReason, resolveDefaultThinkingLevel을 사용합니다. 이는 Anthropic-on-Bedrock 트래픽에 대한 Bedrock 전용 throttle/not-ready/context-overflow 오류 분류를 소유하기 때문입니다. 리플레이 정책은 여전히 동일한 Claude 전용 anthropic-by-model 가드를 공유합니다.
• OpenRouter, Kilocode, Opencode, Opencode Go는 buildReplayPolicy를 passthrough-gemini 리플레이 계열을 통해 사용합니다. 이는 이들이 Gemini 모델을 OpenAI 호환 전송을 통해 프록시하고, 기본 Gemini 리플레이 검증이나 bootstrap 재작성 없이 Gemini thought-signature 정리가 필요하기 때문입니다.
• MiniMax는 buildReplayPolicy를 hybrid-anthropic-openai 리플레이 계열을 통해 사용합니다. 이는 하나의 프로바이더가 Anthropic-message와 OpenAI 호환 의미론을 모두 소유하기 때문입니다. Anthropic 쪽에서는 Claude 전용 thinking 블록 제거를 유지하면서 reasoning 출력 모드를 다시 기본값으로 재정의하고, minimax-fast-mode 스트림 계열은 공유 스트림 경로에서 fast-mode 모델 재작성을 소유합니다.
• Moonshot은 catalog와 wrapStreamFn을 사용합니다. 여전히 공유 OpenAI 전송을 사용하지만 프로바이더 소유 thinking 페이로드 정규화가 필요하기 때문입니다. moonshot-thinking 스트림 계열은 설정과 /think 상태를 해당 프로바이더의 기본 이진 thinking 페이로드에 매핑합니다.
• Kilocode는 catalog, capabilities, wrapStreamFn, isCacheTtlEligible를 사용합니다. 이는 프로바이더 소유 요청 헤더, reasoning 페이로드 정규화, Gemini 전사 힌트, Anthropic 캐시 TTL 게이팅이 필요하기 때문입니다. kilocode-thinking 스트림 계열은 kilo/auto 및 명시적 reasoning 페이로드를 지원하지 않는 기타 프록시 모델 ID를 건너뛰면서 공유 프록시 스트림 경로에서 Kilo thinking 주입을 유지합니다.
• Z.AI는 resolveDynamicModel, prepareExtraParams, wrapStreamFn, isCacheTtlEligible, isBinaryThinking, isModernModelRef, resolveUsageAuth, fetchUsageSnapshot을 사용합니다. 이는 GLM-5 폴백, tool_stream 기본값, 이진 thinking UX, 최신 모델 매칭, 사용량 인증 + 할당량 조회를 모두 소유하기 때문입니다. tool-stream-default-on 스트림 계열은 기본 활성 tool_stream 래퍼가 프로바이더별 수작업 glue에 들어가지 않도록 유지합니다.
• xAI는 normalizeResolvedModel, normalizeTransport, contributeResolvedModelCompat, prepareExtraParams, wrapStreamFn, resolveSyntheticAuth, resolveDynamicModel, isModernModelRef를 사용합니다. 이는 기본 xAI Responses 전송 정규화, Grok fast-mode 별칭 재작성, 기본 tool_stream, strict-tool / reasoning-payload 정리, 플러그인 소유 도구를 위한 폴백 인증 재사용, forward-compat Grok 모델 해석, xAI 도구 스키마 프로필, 지원되지 않는 스키마 키워드, 기본 web_search, HTML 엔티티 도구 호출 인자 디코딩과 같은 프로바이더 소유 호환성 패치를 소유하기 때문입니다.
• Mistral, OpenCode Zen, OpenCode Go는 전사/도구 특수 동작이 코어로 들어오지 않도록 capabilities만 사용합니다.
• byteplus, cloudflare-ai-gateway, huggingface, kimi-coding, nvidia, qianfan, synthetic, together, venice, vercel-ai-gateway, volcengine 같은 카탈로그 전용 번들 프로바이더는 catalog만 사용합니다.
• Qwen은 텍스트 프로바이더용 catalog와 멀티모달 표면용 공유 미디어 이해 및 비디오 생성 등록을 사용합니다.
• MiniMax와 Xiaomi는 추론이 여전히 공유 전송을 통해 실행되더라도 /usage 동작이 플러그인 소유이기 때문에 catalog와 사용량 훅을 함께 사용합니다.

​

런타임 헬퍼

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

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

• 오케스트레이션, 폴백, 설정, 채널 연결은 코어에 유지하세요.
• 벤더 동작은 프로바이더 플러그인에 유지하세요.
• 점진적 확장은 타입을 유지해야 합니다: 새로운 선택적 메서드, 새로운 선택적 결과 필드, 새로운 선택적 기능.
• 비디오 생성도 이미 같은 패턴을 따릅니다:
  • 코어가 기능 계약과 런타임 헬퍼를 소유합니다
  • 벤더 플러그인은 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.*는 이미지/오디오/비디오 이해를 위한 선호되는 공유 표면입니다.
• 코어 미디어 이해 오디오 설정(tools.media.audio)과 프로바이더 폴백 순서를 사용합니다.
• 전사 출력이 생성되지 않으면 { 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는 신뢰된 호출자에 대해서만 이러한 재정의 필드를 적용합니다.
• 플러그인 소유 폴백 실행의 경우, 운영자는 plugins.entries.<id>.subagent.allowModelOverride: true로 명시적으로 동의해야 합니다.
• 신뢰된 플러그인을 특정 정식 provider/model 대상으로 제한하려면 plugins.entries.<id>.subagent.allowedModels를 사용하고, 모든 대상을 명시적으로 허용하려면 "*"를 사용하세요.
• 신뢰되지 않은 플러그인 서브에이전트 실행도 여전히 동작하지만, 재정의 요청은 조용히 폴백되는 대신 거부됩니다.

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

• 프로바이더 선택, 자격 증명 해석, 공유 요청 의미론은 코어에 유지하세요.
• 벤더별 검색 전송에는 웹 검색 프로바이더를 사용하세요.
• api.runtime.webSearch.*는 에이전트 도구 래퍼에 의존하지 않고 검색 동작이 필요한 기능/채널 플러그인을 위한 선호되는 공유 표면입니다.

​

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

​

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: 선택 사항. 같은 플러그인이 기존 라우트 등록을 자체적으로 교체할 수 있게 합니다.
• handler: 라우트가 요청을 처리했을 때 true를 반환합니다.

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

​

Plugin SDK import 경로

• 플러그인 등록 프리미티브에는 openclaw/plugin-sdk/plugin-entry.
• 일반 공유 플러그인 대상 계약에는 openclaw/plugin-sdk/core.
• 루트 openclaw.json Zod 스키마 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는 공유 설정/인증/응답/Webhook 연결을 위한 경로입니다. channel-inbound는 디바운스, 멘션 매칭, 인바운드 멘션 정책 헬퍼, envelope 포맷팅, 인바운드 envelope 컨텍스트 헬퍼의 공유 홈입니다. channel-setup은 좁은 선택적 설치 설정 seam입니다. setup-runtime은 setupEntry / 지연 시작에서 사용하는 런타임 안전 설정 표면이며, import 안전 설정 패치 어댑터를 포함합니다. setup-adapter-runtime은 환경 인식 계정 설정 어댑터 seam입니다. setup-tools는 작은 CLI/archive/docs 헬퍼 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-gateway-runtime, openclaw/plugin-sdk/approval-handler-adapter-runtime, openclaw/plugin-sdk/approval-handler-runtime, 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은 공유 런타임/설정 헬퍼를 위한 경로입니다. telegram-command-config는 Telegram 커스텀 명령 정규화/검증을 위한 좁은 공개 seam이며, 번들된 Telegram 계약 표면을 일시적으로 사용할 수 없더라도 계속 제공됩니다. text-runtime은 assistant-visible-text 제거, markdown 렌더링/청킹 헬퍼, redaction 헬퍼, directive-tag 헬퍼, safe-text 유틸리티를 포함한 공유 텍스트/markdown/로깅 seam입니다.
• 승인 전용 채널 seam은 플러그인에서 하나의 approvalCapability 계약을 우선 사용해야 합니다. 그러면 코어는 승인 동작을 관련 없는 플러그인 필드에 섞는 대신 그 하나의 기능을 통해 승인 인증, 전달, 렌더링, 기본 라우팅, 지연 기본 핸들러 동작을 읽습니다.
• openclaw/plugin-sdk/channel-runtime은 더 이상 권장되지 않으며 이전 플러그인을 위한 호환성 shim으로만 남아 있습니다. 새 코드는 대신 더 좁은 일반 프리미티브를 import해야 하며, 저장소 코드에는 shim에 대한 새 import를 추가해서는 안 됩니다.
• 번들 확장 내부 구조는 비공개로 유지됩니다. 외부 플러그인은 openclaw/plugin-sdk/* 하위 경로만 사용해야 합니다. OpenClaw 코어/테스트 코드는 index.js, api.js, runtime-api.js, setup-entry.js, login-qr-api.js 같은 좁은 범위 파일처럼 플러그인 패키지 루트 아래의 저장소 공개 진입점을 사용할 수 있습니다. 코어나 다른 확장에서 플러그인 패키지의 src/*를 import하지 마세요.
• 저장소 진입점 분리: <plugin-package-root>/api.js는 헬퍼/타입 barrel, <plugin-package-root>/runtime-api.js는 런타임 전용 barrel, <plugin-package-root>/index.js는 번들 플러그인 진입점, <plugin-package-root>/setup-entry.js는 설정 플러그인 진입점입니다.
• 현재 번들 프로바이더 예시:
  • Anthropic은 wrapAnthropicProviderStream, 베타 헤더 헬퍼, service_tier 파싱 같은 Claude 스트림 헬퍼를 위해 api.js / contract-api.js를 사용합니다.
  • OpenAI는 프로바이더 빌더, 기본 모델 헬퍼, 실시간 프로바이더 빌더를 위해 api.js를 사용합니다.
  • OpenRouter는 프로바이더 빌더와 온보딩/설정 헬퍼를 위해 api.js를 사용하고, register.runtime.js는 여전히 저장소 로컬 사용을 위해 일반 plugin-sdk/provider-stream 헬퍼를 다시 export할 수 있습니다.
• 파사드로 로드된 공개 진입점은 활성 런타임 설정 스냅샷이 있을 경우 이를 우선 사용하고, OpenClaw가 아직 런타임 스냅샷을 제공하지 않을 때는 디스크의 해석된 설정 파일로 폴백합니다.
• 일반 공유 프리미티브는 여전히 선호되는 공개 SDK 계약입니다. 번들 채널 브랜드 헬퍼 seam의 작은 예약 호환성 집합은 여전히 존재합니다. 이를 새로운 서드파티 import 대상이 아니라 번들 유지보수/호환성 seam으로 취급하세요. 새로운 크로스채널 계약은 여전히 일반 plugin-sdk/* 하위 경로 또는 플러그인 로컬 api.js / runtime-api.js barrel에 추가되어야 합니다.

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

​

message 도구 스키마

• 버튼 그리드 스타일 페이로드에는 createMessageToolButtonsSchema()
• 구조화된 카드 페이로드에는 createMessageToolCardSchema()

​

채널 대상 해석

• messaging.inferTargetChatType({ to })는 정규화된 대상이 디렉터리 조회 전에 direct, group, channel 중 무엇으로 취급되어야 하는지 결정합니다.
• messaging.targetResolver.looksLikeId(raw, normalized)는 어떤 입력이 디렉터리 검색 대신 곧바로 ID 유사 해석으로 넘어가야 하는지를 코어에 알려줍니다.
• messaging.targetResolver.resolveTarget(...)는 정규화 후 또는 디렉터리 검색 실패 후 코어에 최종 프로바이더 소유 해석이 필요할 때 사용하는 plugin 폴백입니다.
• messaging.resolveOutboundSessionRoute(...)는 대상이 해석된 뒤 프로바이더별 세션 라우트 구성을 소유합니다.

• 피어/그룹 검색 전에 일어나야 하는 범주 결정에는 inferTargetChatType을 사용하세요.
• “이것을 명시적/기본 대상 ID로 취급” 검사에는 looksLikeId를 사용하세요.
• 광범위한 디렉터리 검색이 아니라 프로바이더별 정규화 폴백에는 resolveTarget을 사용하세요.
• chat ID, thread ID, JID, handle, room ID 같은 프로바이더 기본 ID는 일반 SDK 필드가 아니라 target 값 또는 프로바이더별 파라미터 안에 두세요.

​

설정 기반 디렉터리

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

• 쿼리 필터링
• 제한 적용
• 중복 제거/정규화 헬퍼
• ChannelDirectoryEntry[] 구성

​

프로바이더 카탈로그

• 하나의 프로바이더 항목에는 { provider }
• 여러 프로바이더 항목에는 { providers }

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

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

​

읽기 전용 채널 검사

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

• 설명적인 계정 상태만 반환하세요.
• enabled와 configured를 유지하세요.
• 관련이 있다면 다음과 같은 자격 증명 소스/상태 필드를 포함하세요:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• 읽기 전용 가용성을 보고하기 위해 원시 토큰 값을 반환할 필요는 없습니다. 상태 스타일 명령에는 tokenStatus: "available"(및 일치하는 소스 필드)만 반환해도 충분합니다.
• 자격 증명이 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 bot을 통한 셀프 호스팅 채팅.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

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

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

​

컨텍스트 엔진 플러그인

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

​

기능 체크리스트

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

​

기능 템플릿

// 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"]);

• 코어는 기능 계약 + 오케스트레이션을 소유합니다
• 벤더 플러그인은 벤더 구현을 소유합니다
• 기능/채널 플러그인은 런타임 헬퍼를 사용합니다
• 계약 테스트는 소유권을 명시적으로 유지합니다