Plugin SDK 개요

Plugin SDK는 Plugin과 코어 사이의 타입이 지정된 계약입니다. 이 페이지는 무엇을 가져올지와 무엇을 등록할 수 있는지에 대한 참조입니다.

# 가져오기 규칙

항상 특정 하위 경로에서 가져오세요.

각 하위 경로는 작고 독립적인 모듈입니다. 이렇게 하면 시작이 빠르게 유지되고 순환 의존성 문제가 방지됩니다. 채널별 엔트리/빌드 헬퍼에는 openclaw/plugin-sdk/channel-core를 선호하세요. 더 넓은 포괄 표면과 buildChannelConfigSchema 같은 공유 헬퍼에는 openclaw/plugin-sdk/core를 유지하세요.

채널 구성의 경우 채널 소유 JSON Schema를 openclaw.plugin.json#channelConfigs를 통해 게시하세요. plugin-sdk/channel-config-schema 하위 경로는 공유 스키마 기본 요소와 일반 빌더용입니다. OpenClaw의 번들 Plugin은 유지되는 번들 채널 스키마에 plugin-sdk/bundled-channel-config-schema를 사용합니다. 사용 중단된 호환성 내보내기는 plugin-sdk/channel-config-schema-legacy에 남아 있습니다. 두 번들 스키마 하위 경로 모두 새 Plugin의 패턴이 아닙니다.

# 하위 경로 참조

Plugin SDK는 영역별로 그룹화된 좁은 하위 경로 집합(Plugin 엔트리, 채널, 공급자, 인증, 런타임, 기능, 메모리, 예약된 번들 Plugin 헬퍼)으로 노출됩니다. 그룹화되고 링크된 전체 카탈로그는 Plugin SDK 하위 경로를 참조하세요.

생성된 200개 이상의 하위 경로 목록은 scripts/lib/plugin-sdk-entrypoints.json에 있습니다.

# 등록 API

register(api) 콜백은 다음 메서드가 있는 OpenClawPluginApi 객체를 받습니다.

# 기능 등록

메서드	등록하는 항목
api.registerProvider(...)	텍스트 추론(LLM)
api.registerAgentHarness(...)	실험적 저수준 에이전트 실행기
api.registerCliBackend(...)	로컬 CLI 추론 백엔드
api.registerChannel(...)	메시징 채널
api.registerSpeechProvider(...)	텍스트 음성 변환 / STT 합성
api.registerRealtimeTranscriptionProvider(...)	스트리밍 실시간 전사
api.registerRealtimeVoiceProvider(...)	양방향 실시간 음성 세션
api.registerMediaUnderstandingProvider(...)	이미지/오디오/비디오 분석
api.registerImageGenerationProvider(...)	이미지 생성
api.registerMusicGenerationProvider(...)	음악 생성
api.registerVideoGenerationProvider(...)	비디오 생성
api.registerWebFetchProvider(...)	웹 가져오기 / 스크래핑 공급자
api.registerWebSearchProvider(...)	웹 검색

# 도구와 명령

메서드	등록하는 항목
api.registerTool(tool, opts?)	에이전트 도구(필수 또는 { optional: true })
api.registerCommand(def)	사용자 지정 명령(LLM 우회)

에이전트에 짧은 명령 소유 라우팅 힌트가 필요할 때 Plugin 명령은 agentPromptGuidance를 설정할 수 있습니다. 해당 텍스트는 명령 자체에 관한 내용으로 유지하세요. 공급자 또는 Plugin별 정책을 코어 프롬프트 빌더에 추가하지 마세요.

# 인프라

메서드	등록하는 항목
api.registerHook(events, handler, opts?)	이벤트 훅
api.registerHttpRoute(params)	Gateway HTTP 엔드포인트
api.registerGatewayMethod(name, handler)	Gateway RPC 메서드
api.registerGatewayDiscoveryService(service)	로컬 Gateway 검색 광고자
api.registerCli(registrar, opts?)	CLI 하위 명령
api.registerService(service)	백그라운드 서비스
api.registerInteractiveHandler(registration)	대화형 핸들러
api.registerAgentToolResultMiddleware(...)	런타임 도구 결과 미들웨어
api.registerMemoryPromptSupplement(builder)	추가형 메모리 인접 프롬프트 섹션
api.registerMemoryCorpusSupplement(adapter)	추가형 메모리 검색/읽기 말뭉치

# 워크플로 Plugin용 호스트 훅

호스트 훅은 공급자, 채널 또는 도구만 추가하는 대신 호스트 수명 주기에 참여해야 하는 Plugin을 위한 SDK 경계입니다. 이는 일반 계약입니다. Plan Mode에서 사용할 수 있지만, 승인 워크플로, 작업 공간 정책 게이트, 백그라운드 모니터, 설정 마법사, UI 동반 Plugin도 사용할 수 있습니다.

메서드	소유하는 계약
api.registerSessionExtension(...)	Gateway 세션을 통해 투영되는 Plugin 소유 JSON 호환 세션 상태
api.enqueueNextTurnInjection(...)	한 세션의 다음 에이전트 턴에 주입되는 내구성 있는 정확히 한 번의 컨텍스트
api.registerTrustedToolPolicy(...)	도구 매개변수를 차단하거나 다시 쓸 수 있는 번들/신뢰된 사전 Plugin 도구 정책
api.registerToolMetadata(...)	도구 구현을 변경하지 않는 도구 카탈로그 표시 메타데이터
api.registerCommand(...)	범위가 지정된 Plugin 명령; 명령 결과는 continueAgent: true를 설정할 수 있음; Discord 네이티브 명령은 descriptionLocalizations 지원
api.registerControlUiDescriptor(...)	세션, 도구, 실행 또는 설정 표면을 위한 Control UI 기여 설명자
api.registerRuntimeLifecycle(...)	재설정/삭제/다시 로드 경로에서 Plugin 소유 런타임 리소스에 대한 정리 콜백
api.registerAgentEventSubscription(...)	워크플로 상태와 모니터를 위한 정제된 이벤트 구독
api.setRunContext(...) / getRunContext(...) / clearRunContext(...)	터미널 실행 수명 주기에서 정리되는 실행별 Plugin 임시 상태
api.registerSessionSchedulerJob(...)	결정적 정리가 있는 Plugin 소유 세션 스케줄러 작업 레코드

계약은 의도적으로 권한을 나눕니다.

• 외부 Plugin은 세션 확장, UI 설명자, 명령, 도구 메타데이터, 다음 턴 주입, 일반 훅을 소유할 수 있습니다.
• 신뢰된 도구 정책은 일반 before_tool_call 훅보다 먼저 실행되며, 호스트 안전 정책에 참여하므로 번들 전용입니다.
• 예약된 명령 소유권은 번들 전용입니다. 외부 Plugin은 자체 명령 이름 또는 별칭을 사용해야 합니다.
• allowPromptInjection=false는 agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, 레거시 before_agent_start의 프롬프트 필드, enqueueNextTurnInjection을 포함한 프롬프트 변경 훅을 비활성화합니다.

Plan이 아닌 소비자의 예:

Plugin 원형	사용되는 훅
승인 워크플로	세션 확장, 명령 계속, 다음 턴 주입, UI 설명자
예산/작업 공간 정책 게이트	신뢰된 도구 정책, 도구 메타데이터, 세션 투영
백그라운드 수명 주기 모니터	런타임 수명 주기 정리, 에이전트 이벤트 구독, 세션 스케줄러 소유권/정리, Heartbeat 프롬프트 기여, UI 설명자
설정 또는 온보딩 마법사	세션 확장, 범위가 지정된 명령, Control UI 설명자

도구 결과 미들웨어를 사용하는 시점

번들 Plugin은 실행 후 런타임이 해당 결과를 모델에 다시 전달하기 전에 도구 결과를 다시 써야 할 때 api.registerAgentToolResultMiddleware(...)를 사용할 수 있습니다. 이는 tokenjuice 같은 비동기 출력 리듀서를 위한 신뢰된 런타임 중립 경계입니다.

번들 Plugin은 각 대상 런타임에 대해 contracts.agentToolResultMiddleware를 선언해야 합니다. 예: ["pi", "codex"]. 외부 Plugin은 이 미들웨어를 등록할 수 없습니다. 모델 전 도구 결과 타이밍이 필요하지 않은 작업에는 일반 OpenClaw Plugin 훅을 유지하세요. 이전의 Pi 전용 임베디드 확장 팩터리 등록 경로는 제거되었습니다.

# Gateway 검색 등록

api.registerGatewayDiscoveryService(...)를 사용하면 Plugin이 mDNS/Bonjour 같은 로컬 discovery 전송 방식에서 활성 Gateway를 광고할 수 있습니다. 로컬 discovery가 활성화된 경우 OpenClaw는 Gateway 시작 중 서비스를 호출하고, 현재 Gateway 포트와 비밀이 아닌 TXT 힌트 데이터를 전달하며, Gateway 종료 중 반환된 stop 핸들러를 호출합니다.

api.registerGatewayDiscoveryService({
  id: "my-discovery",
  async advertise(ctx) {
    const handle = await startMyAdvertiser({
      gatewayPort: ctx.gatewayPort,
      tls: ctx.gatewayTlsEnabled,
      displayName: ctx.machineDisplayName,
    });
    return { stop: () => handle.stop() };
  },
});

Gateway discovery Plugin은 광고된 TXT 값을 비밀 정보나 인증으로 취급해서는 안 됩니다. Discovery는 라우팅 힌트이며, Gateway 인증과 TLS 고정이 여전히 신뢰를 담당합니다.

# CLI 등록 메타데이터

api.registerCli(registrar, opts?)는 두 종류의 최상위 메타데이터를 받습니다.

• commands: 등록자가 소유한 명시적 명령 루트
• descriptors: 루트 CLI 도움말, 라우팅, 지연 Plugin CLI 등록에 사용되는 구문 분석 시점 명령 descriptor

일반 루트 CLI 경로에서 Plugin 명령을 지연 로드 상태로 유지하려면, 해당 등록자가 노출하는 모든 최상위 명령 루트를 포함하는 descriptors를 제공하세요.

api.registerCli(
  async ({ program }) => {
    const { registerMatrixCli } = await import("./src/cli.js");
    registerMatrixCli({ program });
  },
  {
    descriptors: [
      {
        name: "matrix",
        description: "Manage Matrix accounts, verification, devices, and profile state",
        hasSubcommands: true,
      },
    ],
  },
);

지연 루트 CLI 등록이 필요하지 않은 경우에만 commands를 단독으로 사용하세요. 해당 즉시 로드 호환성 경로는 계속 지원되지만, 구문 분석 시점 지연 로딩을 위한 descriptor 기반 자리표시자를 설치하지는 않습니다.

# CLI 백엔드 등록

api.registerCliBackend(...)를 사용하면 Plugin이 codex-cli 같은 로컬 AI CLI 백엔드의 기본 config를 소유할 수 있습니다.

• 백엔드 id는 codex-cli/gpt-5 같은 모델 참조에서 제공자 prefix가 됩니다.
• 백엔드 config는 agents.defaults.cliBackends.<id>와 동일한 형태를 사용합니다.
• 사용자 config가 여전히 우선합니다. OpenClaw는 CLI를 실행하기 전에 agents.defaults.cliBackends.<id>를 Plugin 기본값 위에 병합합니다.
• 백엔드가 병합 후 호환성 재작성을 필요로 하는 경우 normalizeConfig를 사용하세요 (예: 이전 플래그 형태 정규화).
• OpenClaw thinking 수준을 네이티브 effort 플래그에 매핑하는 것처럼 CLI 방언에 속하는 요청 범위 argv 재작성에는 resolveExecutionArgs를 사용하세요.

# 배타적 슬롯

메서드	등록하는 항목
api.registerContextEngine(id, factory)	컨텍스트 엔진(한 번에 하나만 활성). assemble() 콜백은 엔진이 프롬프트 추가 내용을 맞춤화할 수 있도록 availableTools와 citationsMode를 받습니다.
api.registerMemoryCapability(capability)	통합 메모리 기능
api.registerMemoryPromptSection(builder)	메모리 프롬프트 섹션 빌더
api.registerMemoryFlushPlan(resolver)	메모리 flush plan resolver
api.registerMemoryRuntime(runtime)	메모리 런타임 adapter

# 메모리 embedding adapter

메서드	등록하는 항목
api.registerMemoryEmbeddingProvider(adapter)	활성 Plugin용 메모리 embedding adapter

• registerMemoryCapability는 권장되는 배타적 메모리 Plugin API입니다.
• registerMemoryCapability는 companion Plugin이 특정 메모리 Plugin의 비공개 layout에 접근하는 대신 openclaw/plugin-sdk/memory-host-core를 통해 내보낸 메모리 artifact를 사용할 수 있도록 publicArtifacts.listArtifacts(...)도 노출할 수 있습니다.
• registerMemoryPromptSection, registerMemoryFlushPlan, registerMemoryRuntime은 레거시 호환 배타적 메모리 Plugin API입니다.
• MemoryFlushPlan.model은 활성 fallback chain을 상속하지 않고 flush turn을 ollama/qwen3:8b 같은 정확한 provider/model 참조에 고정할 수 있습니다.
• registerMemoryEmbeddingProvider를 사용하면 활성 메모리 Plugin이 하나 이상의 embedding adapter ID(예: openai, gemini 또는 사용자 지정 Plugin 정의 ID)를 등록할 수 있습니다.
• agents.defaults.memorySearch.provider 및 agents.defaults.memorySearch.fallback 같은 사용자 config는 등록된 adapter ID에 대해 resolve됩니다.

# 이벤트 및 lifecycle

메서드	수행하는 작업
api.on(hookName, handler, opts?)	타입 지정 lifecycle hook
api.onConversationBindingResolved(handler)	대화 binding 콜백

예시, 일반적인 hook 이름, guard semantics는 Plugin hook을 참조하세요.

# Hook 결정 semantics

• before_tool_call: { block: true }를 반환하면 terminal입니다. 어떤 handler든 이를 설정하면 더 낮은 priority handler는 건너뜁니다.
• before_tool_call: { block: false }를 반환하면 override가 아니라 결정 없음(block 생략과 동일)으로 처리됩니다.
• before_install: { block: true }를 반환하면 terminal입니다. 어떤 handler든 이를 설정하면 더 낮은 priority handler는 건너뜁니다.
• before_install: { block: false }를 반환하면 override가 아니라 결정 없음(block 생략과 동일)으로 처리됩니다.
• reply_dispatch: { handled: true, ... }를 반환하면 terminal입니다. 어떤 handler든 dispatch를 claim하면 더 낮은 priority handler와 기본 모델 dispatch 경로는 건너뜁니다.
• message_sending: { cancel: true }를 반환하면 terminal입니다. 어떤 handler든 이를 설정하면 더 낮은 priority handler는 건너뜁니다.
• message_sending: { cancel: false }를 반환하면 override가 아니라 결정 없음(cancel 생략과 동일)으로 처리됩니다.
• message_received: inbound thread/topic 라우팅이 필요할 때는 타입 지정 threadId 필드를 사용하세요. 채널별 추가 정보에는 metadata를 유지하세요.
• message_sending: 채널별 metadata로 fallback하기 전에 타입 지정 replyToId / threadId 라우팅 필드를 사용하세요.
• gateway_start: 내부 gateway:startup hook에 의존하는 대신 gateway 소유 시작 상태에는 ctx.config, ctx.workspaceDir, ctx.getCron?.()을 사용하세요.
• cron_changed: gateway 소유 Cron lifecycle 변경을 관찰합니다. 외부 wake scheduler를 동기화할 때 event.job?.state?.nextRunAtMs와 ctx.getCron?.()을 사용하고, due check 및 실행의 진실 공급원은 OpenClaw로 유지하세요.

# API 객체 필드

필드	타입	설명
api.id	string	Plugin ID
api.name	string	표시 이름
api.version	string?	Plugin 버전(선택 사항)
api.description	string?	Plugin 설명(선택 사항)
api.source	string	Plugin 소스 경로
api.rootDir	string?	Plugin 루트 디렉터리(선택 사항)
api.config	OpenClawConfig	현재 config 스냅샷(사용 가능한 경우 활성 인메모리 런타임 스냅샷)
api.pluginConfig	Record<string, unknown>	plugins.entries.<id>.config의 Plugin별 config
api.runtime	PluginRuntime	런타임 helper
api.logger	PluginLogger	범위 지정 logger(debug, info, warn, error)
api.registrationMode	PluginRegistrationMode	현재 로드 모드; "setup-runtime"은 가벼운 full-entry 전 startup/setup window입니다
api.resolvePath(input)	(string) => string	Plugin 루트를 기준으로 경로 resolve

# 내부 모듈 규칙

Plugin 내부에서는 내부 import에 로컬 barrel 파일을 사용하세요.

my-plugin/
  api.ts            # Public exports for external consumers
  runtime-api.ts    # Internal-only runtime exports
  index.ts          # Plugin entry point
  setup-entry.ts    # Lightweight setup-only entry (optional)

Facade로 로드되는 번들 Plugin 공개 surface(api.ts, runtime-api.ts, index.ts, setup-entry.ts 및 유사한 공개 entry 파일)는 OpenClaw가 이미 실행 중일 때 활성 런타임 config 스냅샷을 우선 사용합니다. 아직 런타임 스냅샷이 없으면 디스크의 resolved config 파일로 fallback합니다. 패키징된 번들 Plugin facade는 OpenClaw의 Plugin facade loader를 통해 로드해야 합니다. dist/extensions/...에서 직접 import하면 패키징된 설치가 Plugin 소유 코드에 사용하는 manifest 및 런타임 sidecar check를 우회합니다.

Provider Plugin은 helper가 의도적으로 provider별이며 아직 generic SDK subpath에 속하지 않는 경우 좁은 Plugin 로컬 contract barrel을 노출할 수 있습니다. 번들 예시:

• Anthropic: Claude beta-header 및 service_tier stream helper를 위한 공개 api.ts / contract-api.ts seam.
• @openclaw/openai-provider: api.ts는 provider builder, default-model helper 및 realtime provider builder를 내보냅니다.
• @openclaw/openrouter-provider: api.ts는 provider builder와 onboarding/config helper를 내보냅니다.

# 관련 항목