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 하위 경로를 참조하세요.

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

등록 API

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

기능 등록

워커 제공자는 Plugin 매니페스트의 contracts.workerProviders에도 해당 ID를 선언해야 합니다. 코어는 provision(profile, operationId) 전에 지속적인 의도를 저장합니다. 제공자는 외부 할당 전에 설정을 검증하고 영구적인 프로필 거부 시 WorkerProviderError를 발생시킵니다. 작업 ID가 반복되면 provision은 동일한 임대를 채택해야 합니다. 코어는 검증된 프로필 설정을 임대와 함께 저장하고 해당 스냅샷을 destroy({ leaseId, profile })와 inspect({ leaseId, profile })에 제공합니다. destroy는 멱등성을 가져야 하며, inspect는 active, destroyed 또는 unknown을 반환합니다. 이를 통해 제공자는 Gateway 재시작 또는 명명된 프로필 제거 이후에도 수명 주기 호출을 라우팅할 수 있습니다. SSH 엔드포인트는 keyRef에 인라인 키 자료가 아닌 SecretRef를 사용하며, 신뢰할 수 있는 프로비저닝 출력의 hostKey를 호스트 이름이나 주석 없이 정확히 algorithm base64 형식으로 포함합니다. 코어는 hostKey를 고정하며 첫 연결에서 받은 키를 절대 신뢰하지 않습니다. 동적 keyRef를 생성하는 제공자는 resolveSshIdentity({ leaseId, profile, keyRef })를 구현할 수 있습니다. 이 메서드가 있으면 해당 리졸버가 최종 권한을 가지며, 이 메서드가 없는 제공자는 구성된 범용 비밀 리졸버를 사용합니다. 갱신 가능한 임대를 사용하는 제공자는 renew(leaseId)도 구현할 수 있습니다. inspect는 일시적이거나 확정할 수 없는 실패 시 예외를 발생시켜야 합니다. 권한 있는 확인을 통해 부재가 확정된 경우에만 unknown을 반환하세요. 코어는 활성 로컬 레코드를 고립 상태로 표시하거나, 저장된 폐기 요청 이후에는 해당 부재를 정리 완료로 처리합니다.

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

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

도구 및 명령

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

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

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

agentPromptGuidance: [  "전역 명령 힌트.",  { text: "기본 OpenClaw 프롬프트에만 이를 표시합니다.", 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가 아닌 프롬프트 표면에서 계속 사용할 수 있습니다.

Node 호스트 명령은 Gateway 프로세스 내부가 아니라 연결된 Node 호스트에서 실행됩니다. agentTool이 있으면 Node는 Gateway 연결에 성공한 후 설명자를 게시합니다. Gateway는 해당 Node가 연결되어 있고 설명자의 command가 Node의 승인된 명령 범위에 포함된 동안에만 이를 에이전트 실행에 노출합니다. 위험하지 않은 명령을 기본 Node 명령 허용 목록에 포함하려면 agentTool.defaultPlatforms를 설정하세요. 그렇지 않으면 명시적인 gateway.nodes.allowCommands 또는 Node 호출 정책이 필요합니다. agentTool.name은 제공자에서 안전하게 사용할 수 있어야 합니다. 문자로 시작하고 문자, 숫자, 밑줄 또는 하이픈만 사용하며 64자 이내여야 합니다. MCP 기반 Node 도구는 카탈로그 및 도구 검색 화면에 원격 MCP 서버/도구 ID를 표시할 수 있도록 agentTool.mcp 메타데이터를 설정할 수 있지만, 실행은 여전히 게시된 Node 명령을 통해 이루어집니다.

인프라

메모리 프롬프트 보충 빌더는 선택적 agentId, agentSessionKey, sandboxed 컨텍스트를 받습니다. 메모리 코퍼스 보충의 search 및 get 호출은 선택적 agentId와 sandboxed 컨텍스트를 받습니다. 에이전트 소유 저장소가 있는 Plugin은 등록 중에 하나의 전역 경로를 캡처하지 말고 호출마다 해당 저장소를 확인해야 합니다. 다중 에이전트 작업에 에이전트 ID가 필요하지만 누락된 경우 임의의 에이전트를 선택하지 말고 안전하게 실패해야 합니다.

Telegram 대화형 핸들러는 핸들러가 성공한 후 Telegram의 일반 수신 에이전트 경로를 통해 텍스트를 전달하도록 { submitText }를 반환할 수 있습니다. 수신 정책이 텍스트를 건너뛰거나 처리에 실패하면 OpenClaw는 콜백 버튼을 유지하므로, 차단 조건이 변경된 후 사용자가 다시 시도할 수 있습니다. 이 결과 필드는 Telegram 전용이며, 다른 채널은 자체 대화형 결과 계약을 유지합니다.

워크플로 Plugin용 호스트 훅

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

surface: "tab" 설명자는 Control UI에 사이드바 탭을 추가합니다. 활성 Plugin의 탭 설명자는 Gateway hello(controlUiTabs)에서 대시보드 클라이언트에 게시되므로 Plugin이 활성화된 동안에만 탭이 표시됩니다. 번들 Plugin은 해당 탭을 위한 일급 대시보드 뷰를 제공할 수 있습니다. 그 밖의 Plugin은 대시보드가 샌드박스 프레임에서 렌더링하는 Plugin HTTP 경로(api.registerHttpRoute(...) 참조)를 path로 설정할 수 있습니다. icon은 대시보드 아이콘 이름 힌트이고, group은 사이드바 섹션(control 또는 agent)을 선택하며, order는 Plugin 탭 간 정렬 순서를 지정하고, requiredScopes는 해당 운영자 범위가 없는 연결에서 탭을 숨깁니다.

api.session.controls.registerControlUiDescriptor({  surface: "tab",  id: "logbook",  label: "Logbook",  description: "Your day as a timeline, built from screen snapshots.",  icon: "sun",  group: "control",  requiredScopes: ["operator.write"],});

새 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 전용입니다. 외부 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"]와 같은 중첩 명령 그룹의 선택적 상위 명령 경로

페어링된 Node 기능에는 api.registerNodeCliFeature(registrar, opts?)를 사용하는 것이 좋습니다. 이는 api.registerCli(..., { parentPath: ["nodes"] })를 감싸는 작은 래퍼이며, openclaw nodes canvas와 같은 명령을 명시적인 Plugin 소유 Node 기능으로 만듭니다.

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

api.registerCli(  async ({ program }) => {    const { registerMatrixCli } = await import("./src/cli.js");    registerMatrixCli({ program });  },  {    descriptors: [      {        name: "matrix",        description: "Matrix 계정, 검증, 기기 및 프로필 상태 관리",        hasSubcommands: true,      },    ],  },);

중첩 명령은 확인된 상위 명령을 program으로 받습니다.

api.registerCli(  async ({ program }) => {    const { registerNodesCanvasCommands } = await import("./src/cli.js");    registerNodesCanvasCommands(program);  },  {    parentPath: ["nodes"],    descriptors: [      {        name: "canvas",        description: "페어링된 Node에서 캔버스 콘텐츠 캡처 또는 렌더링",        hasSubcommands: true,      },    ],  },);

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

CLI 백엔드 등록

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

• 백엔드 id는 my-cli/gpt-5와 같은 모델 참조에서 제공자 접두사가 됩니다.
• 백엔드 config는 agents.defaults.cliBackends.<id>와 동일한 형태를 사용합니다.
• 사용자 구성이 여전히 우선합니다. OpenClaw는 CLI를 실행하기 전에 agents.defaults.cliBackends.<id>를 Plugin 기본값 위에 병합합니다.
• 백엔드가 병합 후 호환성 재작성을 필요로 할 때 normalizeConfig를 사용하세요(예: 이전 플래그 형태 정규화).
• OpenClaw 사고 수준을 네이티브 노력 플래그에 매핑하는 것처럼 CLI 방언에 속하는 요청 범위의 argv 재작성에는 resolveExecutionArgs를 사용하세요. 이 훅은 ctx.executionMode를 받습니다. 일시적인 /btw 호출에 백엔드 네이티브 격리 플래그를 추가하려면 "side-question"을 사용하세요. 이러한 플래그가 다른 경우에는 항상 켜져 있는 CLI의 네이티브 도구를 안정적으로 비활성화한다면 sideQuestionToolMode: "disabled"도 선언하세요.
• 특정 실행에서 모든 네이티브 도구를 비활성화할 수 있는 백엔드는 nativeToolMode: "selectable"을 선언할 수 있습니다. 제한된 호출은 빈 ctx.toolAvailability.native 튜플과 정확한 호스트 격리 MCP 허용 목록을 전달합니다. resolveExecutionArgs는 최종 신규 또는 재개 argv 모두에서 이를 강제해야 합니다. 백엔드가 그렇게 할 수 없으면 OpenClaw는 실패 시 차단합니다.

처음부터 끝까지 다루는 작성 가이드는 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는 사용 중단되었습니다. 새 임베딩 제공자는 api.registerEmbeddingProvider(...)와 contracts.embeddingProviders를 사용해야 합니다.
• 기존 메모리 전용 제공자는 마이그레이션 기간 동안 계속 작동하지만, 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이 아직 로드 중일 수 있습니다.
• cron_reconciled: 시작 또는 스케줄러 다시 로드 후 전체 외부 Cron 프로젝션을 다시 구성합니다. 여기에는 reason과 enabled: false를 포함한 실효 enabled 상태가 포함되며, ctx.getCron?.()은 정확히 조정된 스케줄러를 반환합니다. 영속 프로젝션 작업에 ctx.abortSignal을 전달합니다. 해당 스케줄러 스냅샷이 대체되거나 Gateway가 닫히면 중단됩니다.
• cron_changed: Gateway가 소유하는 Cron 수명 주기 변경을 관찰합니다. scheduled 및 removed 이벤트는 커밋 후 조정 힌트이며, 순서가 보장된 델타 로그가 아닙니다. 작업에 다음 기상 시점이 없으면 예약된 이벤트의 event.nextRunAtMs가 존재하지 않으며, 삭제 이벤트에는 삭제된 작업 스냅샷이 계속 포함됩니다.

외부 기상 스케줄러는 cron_changed 이벤트에 디바운스 또는 병합을 적용한 다음, cron_reconciled가 마지막으로 캡처한 스케줄러에서 전체 영속 뷰를 다시 읽어야 합니다. cron_changed 컨텍스트의 스케줄러를 채택하지 마십시오. 이전 스케줄러에서 분리된 힌트가 이후 다시 로드와 겹칠 수 있습니다.

Gateway 시작 또는 스케줄러 교체 시 로드되는 영속 상태의 전체 스냅샷 트리거로 cron_reconciled를 사용합니다. Plugin만 핫 리로드할 때는 다시 재생되지 않습니다. 관찰 핸들러는 병렬로 실행되며, 실행 후 결과를 기다리지 않는 디스패치는 서로 겹칠 수 있으므로 소비자는 이벤트 완료 순서에 의존해서는 안 됩니다. 기한 확인과 실행의 단일 진실 공급원은 OpenClaw로 유지합니다.

영속 교체, 재시도/백오프, 정상 종료를 지원하는 단일 실행 어댑터는 안전한 외부 Cron 프로젝션을 참조하십시오.

API 객체 필드

내부 모듈 규칙

Plugin 내부 가져오기에는 로컬 배럴 파일을 사용합니다.

my-plugin/  api.ts            # 외부 소비자를 위한 공개 내보내기  runtime-api.ts    # 내부 전용 런타임 내보내기  index.ts          # Plugin 진입점  setup-entry.ts    # 경량 설정 전용 진입점(선택 사항)

퍼사드로 로드되는 번들 Plugin 공개 표면(api.ts, runtime-api.ts, index.ts, setup-entry.ts 및 이와 유사한 공개 진입 파일)은 OpenClaw가 이미 실행 중인 경우 활성 런타임 구성 스냅샷을 우선 사용합니다. 아직 런타임 스냅샷이 없으면 디스크에서 확인된 구성 파일을 대신 사용합니다. 패키징된 번들 Plugin 퍼사드는 OpenClaw의 Plugin 퍼사드 로더를 통해 로드해야 합니다. dist/extensions/...에서 직접 가져오면 패키징된 설치가 Plugin 소유 코드에 사용하는 매니페스트 및 런타임 사이드카 검사를 우회합니다.

도우미가 의도적으로 공급자에 특화되어 있고 아직 일반 SDK 하위 경로에 속하지 않는 경우, 공급자 Plugin은 범위가 좁은 Plugin 로컬 계약 배럴을 노출할 수 있습니다. 번들 예시는 다음과 같습니다.

• Anthropic: Claude 베타 헤더 및 service_tier 스트림 도우미를 위한 공개 api.ts / contract-api.ts 경계.
• @openclaw/openai-provider: api.ts에서 공급자 빌더, 기본 모델 도우미 및 실시간 공급자 빌더를 내보냅니다.
• @openclaw/openrouter-provider: api.ts에서 공급자 빌더와 온보딩/구성 도우미를 내보냅니다.

관련 항목