Plugin SDK 개요

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

Import 규칙

항상 특정 하위 경로에서 import하세요.

각 하위 경로는 작고 독립적인 모듈입니다. 이렇게 하면 시작이 빠르게 유지되고 순환 의존성 문제가 방지됩니다. 채널별 엔트리/빌드 헬퍼에는 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를 사용합니다. 사용 중단된 호환성 export는 plugin-sdk/channel-config-schema-legacy에 남아 있습니다. 두 번들 스키마 하위 경로 모두 새 Plugin을 위한 패턴이 아닙니다.

하위 경로 참조

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

컴파일러 엔트리포인트 인벤토리는 scripts/lib/plugin-sdk-entrypoints.json에 있습니다. 패키지 export는 scripts/lib/plugin-sdk-private-local-only-subpaths.json에 나열된 저장소 로컬 테스트/내부 하위 경로를 제외한 뒤 공개 하위 집합에서 생성됩니다. 공개 export 수를 감사하려면 pnpm plugin-sdk:surface를 실행하세요. 충분히 오래되었고 번들 확장 프로덕션 코드에서 사용되지 않는 사용 중단 공개 하위 경로는 scripts/lib/plugin-sdk-deprecated-public-subpaths.json에서 추적됩니다. 광범위한 사용 중단 재export 배럴은 scripts/lib/plugin-sdk-deprecated-barrel-subpaths.json에서 추적됩니다.

등록 API

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

기능 등록

api.registerEmbeddingProvider(...)로 등록된 임베딩 공급자는 Plugin 매니페스트의 contracts.embeddingProviders에도 나열되어야 합니다. 이는 재사용 가능한 벡터 생성을 위한 범용 임베딩 표면입니다. 메모리 검색은 이 범용 공급자 표면을 사용할 수 있습니다. 이전 api.registerMemoryEmbeddingProvider(...) 및 contracts.memoryEmbeddingProviders 접합부는 기존 메모리별 공급자가 마이그레이션하는 동안의 사용 중단된 호환성입니다.

아직 런타임 batchEmbed(...)를 노출하는 메모리별 공급자는 런타임이 명시적으로 sourceWideBatchEmbed: true를 설정하지 않는 한 기존 파일별 배치 처리 계약에 남습니다. 이 opt-in은 메모리 호스트가 여러 더티 메모리 파일과 활성화된 소스의 청크를 호스트 배치 한도까지 하나의 batchEmbed(...) 호출로 제출할 수 있게 합니다. JSONL 요청 파일을 업로드하는 배치 어댑터는 요청 수 한도뿐 아니라 업로드 크기 상한 전에 공급자 작업도 분할해야 합니다. 공급자는 batch.chunks와 동일한 순서로 입력 청크당 하나의 임베딩을 반환해야 합니다. 공급자가 파일 로컬 배치를 예상하거나 더 큰 소스 전체 작업에서 입력 순서를 보존할 수 없는 경우 이 플래그를 생략하세요.

도구 및 명령

고정된 도구 이름을 가진 단순 도구 전용 Plugin에는 defineToolPlugin을 사용하세요. 혼합 Plugin 또는 완전 동적 도구 등록에는 api.registerTool(...)을 직접 사용하세요.

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

가이드 항목은 모든 프롬프트 표면에 적용되는 레거시 문자열이거나 구조화된 항목일 수 있습니다.

agentPromptGuidance: [  "Global command hint.",  { text: "Only show this in the main OpenClaw prompt.", surfaces: ["openclaw_main"] },];

구조화된 surfaces에는 openclaw_main, codex_app_server, cli_backend, acp_backend, subagent가 포함될 수 있습니다. pi_main은 openclaw_main의 사용 중단된 별칭으로 남아 있습니다. 의도적으로 모든 표면에 대한 가이드인 경우 surfaces를 생략하세요. 빈 surfaces 배열을 전달하지 마세요. 우발적인 범위 손실이 전역 프롬프트 텍스트가 되지 않도록 거부됩니다.

네이티브 Codex 앱 서버 개발자 지침은 다른 프롬프트 표면보다 더 엄격합니다. codex_app_server로 명시적으로 범위가 지정된 가이드만 해당 더 높은 우선순위 레인으로 승격됩니다. 레거시 문자열 가이드와 범위가 지정되지 않은 구조화된 가이드는 호환성을 위해 비 Codex 프롬프트 표면에서 계속 사용할 수 있습니다.

인프라

워크플로 Plugin을 위한 호스트 훅

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

새 Plugin 코드에는 그룹화된 네임스페이스를 사용하세요.

• api.session.state.registerSessionExtension(...)
• api.session.workflow.enqueueNextTurnInjection(...)
• api.session.workflow.registerSessionSchedulerJob(...)
• api.session.workflow.sendSessionAttachment(...)
• api.session.workflow.scheduleSessionTurn(...)
• api.session.workflow.unscheduleSessionTurnsByTag(...)
• api.session.controls.registerSessionAction(...)
• api.session.controls.registerControlUiDescriptor(...)
• api.agent.events.registerAgentEventSubscription(...)
• api.agent.events.emitAgentEvent(...)
• api.runContext.setRunContext(...) / getRunContext(...) / clearRunContext(...)
• api.lifecycle.registerRuntimeLifecycle(...)

동등한 플랫 메서드는 기존 Plugin을 위한 사용 중단된 호환성 별칭으로 계속 사용할 수 있습니다. api.registerSessionExtension, api.enqueueNextTurnInjection, api.registerControlUiDescriptor, api.registerRuntimeLifecycle, api.registerAgentEventSubscription, api.emitAgentEvent, api.setRunContext, api.getRunContext, api.clearRunContext, api.registerSessionSchedulerJob, api.registerSessionAction, api.sendSessionAttachment, api.scheduleSessionTurn 또는 api.unscheduleSessionTurnsByTag를 직접 호출하는 새 Plugin 코드는 추가하지 마세요.

scheduleSessionTurn(...)은 Gateway Cron 스케줄러 위에 있는 세션 범위 편의 기능입니다. Cron은 타이밍을 소유하고 턴이 실행될 때 백그라운드 작업 레코드를 만듭니다. Plugin SDK는 대상 세션, Plugin 소유 이름 지정, 정리만 제한합니다. 작업 자체에 내구성 있는 다단계 Task Flow 상태가 필요한 경우 예약된 턴 안에서 api.runtime.tasks.managedFlows를 사용하세요.

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

• 외부 Plugin은 세션 확장, UI 디스크립터, 명령, 도구 메타데이터, 다음 턴 주입 및 일반 훅을 소유할 수 있습니다.
• 신뢰할 수 있는 도구 정책은 일반 before_tool_call 훅보다 먼저 실행되며 호스트가 신뢰합니다. 번들 정책이 먼저 실행되고, 설치된 Plugin 정책은 명시적 활성화와 contracts.trustedToolPolicies의 로컬 ID가 필요하며, 그다음 Plugin 로드 순서대로 실행됩니다. 정책 ID는 등록하는 Plugin으로 범위가 지정됩니다.
• 예약된 명령 소유권은 번들 전용입니다. 외부 Plugin은 자체 명령 이름이나 별칭을 사용해야 합니다.
• allowPromptInjection=false는 agent_turn_prepare, before_prompt_build, heartbeat_prompt_contribution, 레거시 before_agent_start의 프롬프트 필드, enqueueNextTurnInjection을 포함한 프롬프트 변경 훅을 비활성화합니다.

Plan이 아닌 소비자의 예:

Gateway 탐색 등록

api.registerGatewayDiscoveryService(...)를 사용하면 Plugin이 mDNS/Bonjour 같은 로컬 탐색 전송에서 활성 Gateway를 알릴 수 있습니다. 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 탐색 Plugin은 광고된 TXT 값을 비밀이나 인증으로 취급해서는 안 됩니다. 탐색은 라우팅 힌트입니다. Gateway 인증과 TLS 핀 고정이 여전히 신뢰를 소유합니다.

CLI 등록 메타데이터

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

• commands: 등록자가 소유한 명시적 명령 이름
• descriptors: CLI 도움말, 라우팅, 지연 Plugin CLI 등록에 사용되는 파싱 시점 명령 디스크립터
• parentPath: ["nodes"] 같은 중첩 명령 그룹의 선택적 부모 명령 경로

페어링된 노드 기능에는 api.registerNodeCliFeature(registrar, opts?)를 선호하세요. 이것은 api.registerCli(..., { parentPath: ["nodes"] })를 감싼 작은 래퍼이며 openclaw nodes canvas 같은 명령을 명시적인 Plugin 소유 노드 기능으로 만듭니다.

Plugin 명령을 일반 루트 CLI 경로에서 지연 로드 상태로 유지하려면 해당 등록자가 노출하는 모든 최상위 명령 루트를 포괄하는 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,      },    ],  },);

중첩 명령은 해석된 부모 명령을 program으로 받습니다.

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "Capture or render canvas content from a paired node",        hasSubcommands: true,      },    ],  },);

지연 루트 CLI 등록이 필요하지 않을 때만 commands만 사용하세요. 이 즉시 호환성 경로는 계속 지원되지만, 파싱 시점 지연 로딩을 위한 디스크립터 기반 자리표시자를 설치하지는 않습니다.

CLI 백엔드 등록

api.registerCliBackend(...)를 사용하면 Plugin이 claude-cli 또는 my-cli 같은 로컬 AI CLI 백엔드의 기본 구성을 소유할 수 있습니다.

• 백엔드 id는 my-cli/gpt-5 같은 모델 참조에서 provider 접두사가 됩니다.
• 백엔드 config는 agents.defaults.cliBackends.<id>와 같은 형태를 사용합니다.
• 사용자 구성은 여전히 우선합니다. OpenClaw는 CLI를 실행하기 전에 Plugin 기본값 위에 agents.defaults.cliBackends.<id>를 병합합니다.
• 백엔드가 병합 후 호환성 재작성(예: 이전 플래그 형태 정규화)이 필요할 때는 normalizeConfig를 사용하세요.
• OpenClaw 사고 수준을 네이티브 effort 플래그에 매핑하는 것처럼 CLI 방언에 속하는 요청 범위 argv 재작성에는 resolveExecutionArgs를 사용하세요. 이 훅은 ctx.executionMode를 받습니다. 일시적인 /btw 호출에 백엔드 네이티브 격리 플래그를 추가하려면 "side-question"을 사용하세요. 이러한 플래그가 원래 항상 켜져 있는 CLI에서 네이티브 도구를 안정적으로 비활성화한다면 sideQuestionToolMode: "disabled"도 선언하세요.

엔드투엔드 작성 가이드는 CLI 백엔드 Plugin을 참조하세요.

독점 슬롯

사용 중단된 메모리 임베딩 어댑터

• registerMemoryCapability는 선호되는 독점 메모리 Plugin API입니다.
• registerMemoryCapability는 publicArtifacts.listArtifacts(...)도 노출할 수 있어 동반 Plugin이 특정 메모리 Plugin의 비공개 레이아웃에 접근하는 대신 openclaw/plugin-sdk/memory-host-core를 통해 내보낸 메모리 아티팩트를 사용할 수 있습니다.
• registerMemoryPromptSection, registerMemoryFlushPlan, registerMemoryRuntime은 레거시 호환 독점 메모리 Plugin API입니다.
• MemoryFlushPlan.model은 활성 폴백 체인을 상속하지 않고 ollama/qwen3:8b 같은 정확한 provider/model 참조로 플러시 턴을 고정할 수 있습니다.
• registerMemoryEmbeddingProvider는 사용 중단되었습니다. 새 임베딩 provider는 api.registerEmbeddingProvider(...)와 contracts.embeddingProviders를 사용해야 합니다.
• 기존 메모리 전용 provider는 마이그레이션 기간 동안 계속 작동하지만, Plugin 검사에서는 번들에 포함되지 않은 Plugin에 대해 이를 호환성 부채로 보고합니다.

이벤트와 수명 주기

예시, 일반적인 훅 이름, 가드 의미론은 Plugin 훅을 참조하세요.

훅 결정 의미론

before_install은 Plugin 런타임 수명 주기 훅이며, 운영자 설치 정책 표면이 아닙니다. 허용/차단 결정이 CLI 및 Gateway 기반 설치 또는 업데이트 경로를 포괄해야 할 때는 security.installPolicy를 사용하세요.

• before_tool_call: { block: true }를 반환하면 종료 결정입니다. 어떤 핸들러든 이를 설정하면 더 낮은 우선순위 핸들러는 건너뜁니다.
• before_tool_call: { block: false }를 반환하면 결정 없음(block 생략과 동일)으로 처리되며, 재정의가 아닙니다.
• before_install: { block: true }를 반환하면 종료 결정입니다. 어떤 핸들러든 이를 설정하면 더 낮은 우선순위 핸들러는 건너뜁니다.
• before_install: { block: false }를 반환하면 결정 없음(block 생략과 동일)으로 처리되며, 재정의가 아닙니다.
• reply_dispatch: { handled: true, ... }를 반환하면 종료 결정입니다. 어떤 핸들러든 디스패치를 맡으면 더 낮은 우선순위 핸들러와 기본 모델 디스패치 경로는 건너뜁니다.
• message_sending: { cancel: true }를 반환하면 종료 결정입니다. 어떤 핸들러든 이를 설정하면 더 낮은 우선순위 핸들러는 건너뜁니다.
• message_sending: { cancel: false }를 반환하면 결정 없음(cancel 생략과 동일)으로 처리되며, 재정의가 아닙니다.
• message_received: 인바운드 스레드/주제 라우팅이 필요할 때 타입이 지정된 threadId 필드를 사용하세요. 채널별 추가 항목에는 metadata를 유지하세요.
• message_sending: 채널별 metadata로 폴백하기 전에 타입이 지정된 replyToId / threadId 라우팅 필드를 사용하세요.
• gateway_start: 내부 gateway:startup 훅에 의존하는 대신 Gateway가 소유하는 시작 상태에는 ctx.config, ctx.workspaceDir, ctx.getCron?.()을 사용하세요.
• cron_changed: Gateway가 소유하는 Cron 수명 주기 변경을 관찰합니다. 외부 깨우기 스케줄러를 동기화할 때 event.job?.state?.nextRunAtMs와 ctx.getCron?.()을 사용하고, 만기 확인 및 실행의 신뢰 원본은 OpenClaw로 유지하세요.

API 객체 필드

내부 모듈 규칙

Plugin 내부에서는 내부 가져오기에 로컬 배럴 파일을 사용하세요.

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 공개 표면(api.ts, runtime-api.ts, index.ts, setup-entry.ts 및 유사한 공개 엔트리 파일)은 OpenClaw가 이미 실행 중이면 활성 런타임 구성 스냅샷을 선호합니다. 아직 런타임 스냅샷이 없으면 디스크의 해석된 구성 파일로 폴백합니다. 패키징된 번들 Plugin facade는 OpenClaw의 Plugin facade 로더를 통해 로드해야 합니다. dist/extensions/...에서 직접 가져오면 패키징 설치가 Plugin 소유 코드에 사용하는 매니페스트 및 런타임 사이드카 검사를 우회합니다.

provider Plugin은 헬퍼가 의도적으로 provider 전용이고 아직 일반 SDK 하위 경로에 속하지 않을 때 좁은 Plugin 로컬 계약 배럴을 노출할 수 있습니다. 번들 예시:

• Anthropic: Claude beta-header 및 service_tier 스트림 헬퍼를 위한 공개 api.ts / contract-api.ts 경계.
• @openclaw/openai-provider: api.ts는 provider 빌더, 기본 모델 헬퍼, 실시간 provider 빌더를 내보냅니다.
• @openclaw/openrouter-provider: api.ts는 provider 빌더와 온보딩/구성 헬퍼를 내보냅니다.

관련 항목