Plugin 진입점

모든 plugin은 기본 엔트리 객체를 내보냅니다. SDK는 각 엔트리 형태에 대한 도우미를 제공합니다: defineToolPlugin, definePluginEntry, defineChannelPluginEntry, defineSetupPluginEntry.

패키지 엔트리

설치된 plugin은 소스와 빌드된 엔트리 모두를 가리키도록 package.json openclaw 필드를 설정합니다:

{  "openclaw": {    "extensions": ["./src/index.ts"],    "runtimeExtensions": ["./dist/index.js"],    "setupEntry": "./src/setup-entry.ts",    "runtimeSetupEntry": "./dist/setup-entry.js"  }}

• extensions 및 setupEntry은 소스 엔트리이며 워크스페이스 및 git 체크아웃 개발에 사용됩니다.
• runtimeExtensions 및 runtimeSetupEntry은 설치된 패키지에 권장됩니다. 이를 사용하면 npm 패키지가 런타임 TypeScript 컴파일을 생략할 수 있습니다.
• runtimeExtensions이 있는 경우 배열 길이가 extensions과 일치해야 합니다(엔트리는 위치에 따라 쌍을 이룹니다). runtimeSetupEntry에는 setupEntry이 필요합니다.
• runtimeExtensions/runtimeSetupEntry 아티팩트가 선언되었지만 누락된 경우 설치/검색은 패키징 오류로 실패하며, OpenClaw는 소스로 자동 대체하지 않습니다. 아래의 소스 대체는 런타임 엔트리가 전혀 선언되지 않은 경우에만 적용됩니다.
• 설치된 패키지가 TypeScript 소스 엔트리만 선언한 경우 OpenClaw는 일치하는 빌드된 dist/*.js(또는 .mjs/.cjs) 피어를 찾아 사용하며, 없으면 TypeScript 소스로 대체합니다.
• 모든 엔트리 경로는 plugin 패키지 디렉터리 내부에 있어야 합니다. 런타임 엔트리와 추론된 빌드 JavaScript 피어가 있더라도 외부로 벗어나는 extensions 또는 setupEntry 소스 경로가 유효해지는 것은 아닙니다.

defineToolPlugin

가져오기: openclaw/plugin-sdk/tool-plugin

에이전트 도구만 추가하는 plugin에 사용합니다. 소스를 작게 유지하고 TypeBox 스키마에서 설정 및 도구 매개변수 타입을 추론하며, 일반 반환 값을 OpenClaw 도구 결과 형식으로 래핑하고, openclaw plugins build이 plugin 매니페스트 (contracts.tools, configSchema)에 기록하는 정적 메타데이터를 노출합니다.

  export default defineToolPlugin({  id: "stock-quotes",  name: "Stock Quotes",  description: "Fetch stock quotes.",  configSchema: Type.Object({    apiKey: Type.Optional(Type.String({ description: "API key." })),  }),  tools: (tool) => [    tool({      name: "quote",      label: "Quote",      description: "Fetch a quote.",      parameters: Type.Object({        symbol: Type.String({ description: "Ticker symbol." }),      }),      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),    }),  ],});

• configSchema은 선택 사항입니다. 생략하면 엄격한 빈 객체 스키마를 사용합니다 (생성된 매니페스트에는 여전히 configSchema이 포함됩니다).
• execute은 일반 문자열 또는 JSON으로 직렬화 가능한 값을 반환합니다. 도우미는 이를 텍스트 도구 결과로 래핑하고 details을 원래의 직렬화되지 않은 반환 값으로 설정합니다.
• 사용자 지정 도구 결과를 위해 openclaw/plugin-sdk/tool-results은 textResult 및 jsonResult을 내보냅니다.
• 도구 이름은 정적이므로 openclaw plugins build은 이름을 수동으로 중복 작성하지 않고 선언된 도구에서 contracts.tools을 파생합니다.
• 런타임 로딩은 엄격하게 유지됩니다. 설치된 plugin에는 여전히 openclaw.plugin.json 및 package.json openclaw.extensions이 필요합니다. OpenClaw는 누락된 매니페스트 데이터를 추론하기 위해 plugin 코드를 실행하지 않습니다.

definePluginEntry

가져오기: openclaw/plugin-sdk/plugin-entry

제공자 plugin, 고급 도구 plugin, 훅 plugin 및 메시징 채널이 아닌 모든 항목에 사용합니다.

 export default definePluginEntry({  id: "my-plugin",  name: "My Plugin",  description: "Short summary",  register(api) {    api.registerProvider({/* ... */});    api.registerTool({/* ... */});  },});

• id은 openclaw.plugin.json 매니페스트와 일치해야 합니다.
• 외부 세션 카탈로그는 openclaw/plugin-sdk/session-catalog 및 api.registerSessionCatalog({ id, label, list, read, continueSession?, archive? })을 사용합니다. 코어는 sessions.catalog.* Gateway 메서드를 소유하며, 제공자는 RPC를 등록하지 않고 호스트, 세션 및 정규화된 트랜스크립트 프로젝션을 반환합니다.
• kind은 사용 중단되었습니다. 대신 openclaw.plugin.json 매니페스트의 kind 필드에 독점 슬롯("memory" 또는 "context-engine")을 선언하십시오. 런타임 엔트리 kind은 이전 plugin을 위한 호환성 대체 수단으로만 남아 있습니다.
• configSchema은 지연 평가를 위한 함수일 수 있습니다. OpenClaw는 처음 접근할 때 스키마를 해석하고 메모이제이션하므로 비용이 큰 스키마 빌더는 한 번만 실행됩니다.
• nodeHostCommands 설명자는 isAvailable({ config, env })을 정의할 수 있습니다. false을 반환하면 헤드리스 Node의 Gateway 선언에서 해당 명령과 기능이 생략됩니다. OpenClaw는 Node 로컬 시작 설정을 기준으로 이를 평가합니다. 명령 핸들러는 호출될 때도 가용성을 검증해야 합니다.

defineChannelPluginEntry

가져오기: openclaw/plugin-sdk/channel-core

definePluginEntry을 채널별 배선으로 래핑합니다. api.registerChannel({ plugin })을 자동으로 호출하고, 선택적 루트 도움말 CLI 메타데이터 연결 지점을 노출하며, 등록 모드에 따라 registerFull을 제한합니다.

 export default defineChannelPluginEntry({  id: "my-channel",  name: "My Channel",  description: "Short summary",  plugin: myChannelPlugin,  setRuntime: setMyRuntime,  registerCliMetadata(api) {    api.registerCli(/* ... */);  },  registerFull(api) {    api.registerGatewayMethod(/* ... */);  },});

콜백은 등록 모드별로 실행됩니다(전체 표는 등록 모드 참조):

• setRuntime은 "cli-metadata" 및 "tool-discovery"을 제외한 모든 모드에서 실행됩니다. 런타임 참조를 여기에 저장하며, 일반적으로 createPluginRuntimeStore을 사용합니다.
• registerCliMetadata은 "cli-metadata", "discovery" 및 "full"에서 실행됩니다. 채널 소유 CLI 설명자의 표준 위치로 사용하면 루트 도움말이 활성화를 유발하지 않고, 검색 스냅샷에 정적 명령 메타데이터가 포함되며, 일반 CLI 등록이 전체 plugin 로드와 호환됩니다.
• registerFull은 "full" 및 "tool-discovery"에서만 실행됩니다. "tool-discovery"에서는 채널 등록을 대신하여 실행됩니다. OpenClaw는 registerChannel/setRuntime을 완전히 건너뛰고 registerFull만 호출하므로, 독립 실행형 도구 검색 또는 실행에 채널이 필요로 하는 제공자/도구 등록은 일반 채널 설정 뒤가 아니라 여기에 있어야 합니다.
• 검색 등록은 활성화하지 않지만 가져오기를 하지 않는 것은 아닙니다. OpenClaw는 스냅샷을 빌드하기 위해 신뢰할 수 있는 plugin 엔트리와 채널 plugin 모듈을 평가할 수 있습니다. 최상위 가져오기는 부작용이 없도록 유지하고 소켓, 클라이언트, 워커 및 서비스는 "full" 전용 경로 뒤에 두십시오.
• definePluginEntry과 마찬가지로 configSchema은 지연 팩터리일 수 있습니다. OpenClaw는 처음 접근할 때 해석된 스키마를 메모이제이션합니다.

CLI 등록:

• 루트 CLI 구문 분석 트리에서 사라지지 않으면서 지연 로드할 plugin 소유 루트 CLI 명령에는 api.registerCli(..., { descriptors: [...] })을 사용하십시오. 설명자 이름은 문자 또는 숫자로 시작하고 문자, 숫자, 하이픈 및 밑줄과 일치해야 합니다. OpenClaw는 다른 형태를 거부하고 도움말을 렌더링하기 전에 설명에서 터미널 제어 시퀀스를 제거합니다. 등록자가 노출하는 모든 최상위 명령 루트를 포함하십시오. commands만 사용하면 즉시 로드되는 호환성 경로에 남습니다.
• 페어링된 Node 기능 명령에는 api.registerNodeCliFeature(...)을 사용하여 해당 명령이 openclaw nodes(registerCli(registrar, { parentPath: ["nodes"], ... })과 동일)에 배치되도록 하십시오.
• 다른 중첩 plugin 명령의 경우 parentPath을 추가하고 등록자에게 전달되는 program 객체에 명령을 등록하십시오. OpenClaw는 plugin을 호출하기 전에 이를 상위 명령으로 해석합니다.
• 채널 plugin의 경우 registerCliMetadata에서 CLI 설명자를 등록하고 registerFull은 런타임 전용 작업에 집중하도록 유지하십시오.
• registerFull이 Gateway RPC 메서드도 등록하는 경우 plugin별 접두사에 두십시오. 예약된 코어 관리 네임스페이스(config.*, exec.approvals.*, wizard.*, update.*)는 항상 operator.admin으로 강제 변환됩니다.

defineSetupPluginEntry

가져오기: openclaw/plugin-sdk/channel-core

경량 setup-entry.ts 파일에 사용합니다. 런타임 또는 CLI 배선 없이 { plugin }만 반환합니다.

 export default defineSetupPluginEntry(myChannelPlugin);

OpenClaw는 채널이 비활성화되었거나 구성되지 않았거나 지연 로딩이 활성화된 경우 전체 엔트리 대신 이를 로드합니다. 이 동작이 중요한 경우는 설정 및 구성을 참조하십시오.

defineSetupPluginEntry(...)을 다음의 범위가 좁은 설정 헬퍼 계열과 함께 사용하십시오.

무거운 SDK, CLI 등록 및 장기 실행 런타임 서비스는 전체 엔트리에 유지하십시오.

설정과 런타임 표면을 분리하는 번들 워크스페이스 채널은 대신 openclaw/plugin-sdk/channel-entry-contract의 defineBundledChannelSetupEntry(...)을 사용할 수 있습니다. 이를 사용하면 설정 엔트리에서 설정에 안전한 Plugin/비밀 내보내기를 유지하면서 런타임 setter도 계속 노출할 수 있습니다.

 export default defineBundledChannelSetupEntry({  importMetaUrl: import.meta.url,  plugin: {    specifier: "./channel-plugin-api.js",    exportName: "myChannelPlugin",  },  runtime: {    specifier: "./runtime-api.js",    exportName: "setMyChannelRuntime",  },  registerSetupRuntime(api) {    api.registerHttpRoute({      path: "/my-channel/events",      auth: "plugin",      handler: async (req, res) => {        /* 설정에 안전한 경로 */      },    });  },});

설정 흐름에서 전체 채널 엔트리가 로드되기 전에 경량 런타임 setter 또는 설정에 안전한 Gateway 표면이 실제로 필요한 경우에만 이를 사용하십시오. registerSetupRuntime은 "setup-runtime" 로드에서만 실행됩니다. 지연된 전체 활성화 전에 반드시 존재해야 하는 구성 전용 경로나 메서드로 제한하십시오.

등록 모드

api.registrationMode는 Plugin이 로드된 방식을 알려줍니다.

defineChannelPluginEntry는 이 분리를 자동으로 처리합니다. 채널에 definePluginEntry을 직접 사용하는 경우 모드를 직접 확인하고 "tool-discovery"이 채널 등록을 건너뛴다는 점을 기억하십시오.

register(api) {  if (    api.registrationMode === "cli-metadata" ||    api.registrationMode === "discovery" ||    api.registrationMode === "full"  ) {    api.registerCli(/* ... */);    if (api.registrationMode === "cli-metadata") return;  }   if (api.registrationMode === "tool-discovery") {    // 기능 전용 표면(제공자/도구)을 등록하며 채널은 등록하지 않습니다.    return;  }   api.registerChannel({ plugin: myPlugin });  if (api.registrationMode !== "full") return;   // 무거운 런타임 전용 등록  api.registerService(/* ... */);}

장기 실행 서비스는 서비스 컨텍스트를 통해 작은 무효화 또는 수명 주기 이벤트를 내보낼 수 있습니다.

api.registerService({  id: "index-events",  start(ctx) {    ctx.gatewayEvents?.emit("changed", { revision: 1 }, { scope: "operator.read" });  },});

OpenClaw는 이를 plugin.<plugin-id>.changed로 네임스페이스화합니다. 이벤트 이름은 소문자 세그먼트 하나여야 하고, 페이로드는 크기가 제한된 JSON이어야 하며, 범위는 operator.read, operator.write 또는 operator.admin여야 합니다. 이미터는 서비스 수명 동안에만 존재하며 중지 또는 시작 실패 후에는 취소됩니다. 권한이 부여된 클라이언트가 Plugin의 범위 지정 Gateway 메서드를 통해 정식 상태를 다시 읽도록 전체 레코드보다 버전 또는 무효화 페이로드를 사용하는 것이 좋습니다.

검색 모드는 활성화하지 않는 레지스트리 스냅샷을 생성합니다. OpenClaw가 채널 기능과 정적 CLI 설명자를 등록할 수 있도록 Plugin 엔트리 및 채널 Plugin 객체를 계속 평가할 수 있습니다. 검색 중 모듈 평가는 신뢰할 수 있지만 가볍게 유지하십시오. 최상위 수준에서 네트워크 클라이언트, 하위 프로세스, 리스너, 데이터베이스 연결, 백그라운드 워커, 자격 증명 읽기 또는 기타 실제 런타임 부작용을 실행하지 마십시오.

"setup-runtime"을 전체 번들 채널 런타임에 다시 진입하지 않고 설정 전용 시작 표면이 존재해야 하는 기간으로 취급하십시오. 적합한 항목은 채널 등록, 설정에 안전한 HTTP 경로, 설정에 안전한 Gateway 메서드 및 위임된 설정 헬퍼입니다. 무거운 백그라운드 서비스, CLI 등록기 및 제공자/클라이언트 SDK 부트스트랩은 여전히 "full"에 속합니다.

Plugin 형태

OpenClaw는 로드된 Plugin을 등록 동작에 따라 분류합니다.

Plugin의 형태를 확인하려면 openclaw plugins inspect <id>을 사용하십시오.

관련 항목

• SDK 개요 - 등록 API 및 하위 경로 참조
• 런타임 헬퍼 - api.runtime 및 createPluginRuntimeStore
• 설정 및 구성 - 매니페스트, 설정 엔트리, 지연 로딩
• 채널 Plugin - ChannelPlugin 객체 빌드
• 제공자 Plugin - 제공자 등록 및 후크