메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

모든 Plugin은 기본 엔트리 객체를 내보냅니다. SDK는 이를 생성하기 위한 세 가지 헬퍼를 제공합니다. 설치된 Plugin의 경우, package.json은 사용 가능한 경우 런타임 로딩이 빌드된 JavaScript를 가리키도록 해야 합니다. 
{
  "openclaw": {
    "extensions": ["./src/index.ts"],
    "runtimeExtensions": ["./dist/index.js"],
    "setupEntry": "./src/setup-entry.ts",
    "runtimeSetupEntry": "./dist/setup-entry.js"
  }
}
extensions와 setupEntry는 워크스페이스 및 git 체크아웃 개발을 위한 소스 엔트리로 계속 유효합니다. OpenClaw가 설치된 패키지를 로드할 때는 runtimeExtensions와 runtimeSetupEntry가 선호되며, npm 패키지가 런타임 TypeScript 컴파일을 피할 수 있게 합니다. 명시적 런타임 엔트리는 필수입니다. runtimeSetupEntry에는 setupEntry가 필요하며, runtimeExtensions 또는 runtimeSetupEntry 아티팩트가 없으면 소스로 조용히 폴백하는 대신 설치/검색이 실패합니다. 설치된 패키지가 TypeScript 소스 엔트리만 선언한 경우 OpenClaw는 일치하는 빌드된 dist/*.js 피어가 있으면 이를 사용한 다음, TypeScript 소스로 폴백합니다. 모든 엔트리 경로는 Plugin 패키지 디렉터리 내부에 있어야 합니다. 런타임 엔트리와 추론된 빌드된 JavaScript 피어는 패키지 밖으로 벗어나는 extensions 또는 setupEntry 소스 경로를 유효하게 만들지 않습니다.
연습 안내를 찾고 있나요? 단계별 가이드는 채널 Plugin 또는 제공자 Plugin을 참조하세요.

​
definePluginEntry

가져오기: openclaw/plugin-sdk/plugin-entry 제공자 Plugin, 도구 Plugin, 훅 Plugin 및 메시징 채널이 아닌 모든 항목에 사용합니다. 
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Short summary",
  register(api) {
    api.registerProvider({
      /* ... */
    });
    api.registerTool({
      /* ... */
    });
  },
});
필드유형필수기본값
idstring예-
namestring예-
descriptionstring예-
kindstring아니요-
configSchemaOpenClawPluginConfigSchema | () => OpenClawPluginConfigSchema아니요빈 객체 스키마
register(api: OpenClawPluginApi) => void예-
  • id는 openclaw.plugin.json 매니페스트와 일치해야 합니다.
  • kind는 전용 슬롯인 "memory" 또는 "context-engine"에 사용됩니다.
  • configSchema는 지연 평가를 위해 함수일 수 있습니다.
  • OpenClaw는 처음 접근할 때 해당 스키마를 해석하고 메모이즈하므로, 비용이 큰 스키마 빌더는 한 번만 실행됩니다.

​
defineChannelPluginEntry

가져오기: openclaw/plugin-sdk/channel-core 채널별 연결과 함께 definePluginEntry를 래핑합니다. api.registerChannel({ plugin })을 자동으로 호출하고, 선택적 루트 도움말 CLI 메타데이터 지점을 노출하며, 등록 모드에 따라 registerFull을 제한합니다. 
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineChannelPluginEntry({
  id: "my-channel",
  name: "My Channel",
  description: "Short summary",
  plugin: myChannelPlugin,
  setRuntime: setMyRuntime,
  registerCliMetadata(api) {
    api.registerCli(/* ... */);
  },
  registerFull(api) {
    api.registerGatewayMethod(/* ... */);
  },
});
필드유형필수기본값
idstring예-
namestring예-
descriptionstring예-
pluginChannelPlugin예-
configSchemaOpenClawPluginConfigSchema | () => OpenClawPluginConfigSchema아니요빈 객체 스키마
setRuntime(runtime: PluginRuntime) => void아니요-
registerCliMetadata(api: OpenClawPluginApi) => void아니요-
registerFull(api: OpenClawPluginApi) => void아니요-
  • setRuntime은 런타임 참조를 저장할 수 있도록 등록 중에 호출됩니다(일반적으로 createPluginRuntimeStore를 통해). CLI 메타데이터 캡처 중에는 건너뜁니다.
  • registerCliMetadata는 api.registrationMode === "cli-metadata", api.registrationMode === "discovery", 그리고 api.registrationMode === "full" 중에 실행됩니다. 루트 도움말이 활성화를 유발하지 않도록 유지하고, 검색 스냅샷에 정적 명령 메타데이터가 포함되도록 하며, 일반 CLI 명령 등록이 전체 Plugin 로드와 호환되도록 하기 위한 채널 소유 CLI 설명자의 표준 위치로 사용하세요.
  • 검색 등록은 비활성화 방식이지만, import-free는 아닙니다. OpenClaw는 스냅샷을 빌드하기 위해 신뢰된 Plugin 엔트리와 채널 Plugin 모듈을 평가할 수 있으므로, 최상위 import에는 부작용이 없게 유지하고 소켓, 클라이언트, 워커, 서비스는 "full" 전용 경로 뒤에 두세요.
  • registerFull은 api.registrationMode === "full"일 때만 실행됩니다. setup-only 로딩 중에는 건너뜁니다.
  • definePluginEntry와 마찬가지로 configSchema는 지연 팩터리일 수 있으며 OpenClaw는 처음 접근할 때 해석된 스키마를 메모이즈합니다.
  • Plugin 소유 루트 CLI 명령의 경우, 루트 CLI 파스 트리에서 사라지지 않으면서 명령을 지연 로드 상태로 유지하려면 api.registerCli(..., { descriptors: [...] })를 선호하세요. 쌍을 이루는 노드 기능 명령에는 명령이 openclaw nodes 아래에 위치하도록 api.registerNodeCliFeature(...)를 선호하세요. 그 밖의 중첩된 Plugin 명령에는 parentPath를 추가하고 등록자에 전달된 program 객체에 명령을 등록하세요. OpenClaw는 Plugin을 호출하기 전에 이를 부모 명령으로 해석합니다. 채널 Plugin의 경우 해당 설명자를 registerCliMetadata(...)에서 등록하고 registerFull(...)은 런타임 전용 작업에 집중하는 방식을 선호하세요.
  • registerFull(...)이 Gateway RPC 메서드도 등록하는 경우, Plugin별 접두사에 유지하세요. 예약된 핵심 관리자 네임스페이스(config.*, exec.approvals.*, wizard.*, update.*)는 항상 operator.admin으로 강제 변환됩니다.

​
defineSetupPluginEntry

가져오기: openclaw/plugin-sdk/channel-core 가벼운 setup-entry.ts 파일에 사용합니다. 런타임 또는 CLI 연결 없이 { plugin }만 반환합니다. 
import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";

export default defineSetupPluginEntry(myChannelPlugin);
OpenClaw는 채널이 비활성화되었거나, 구성되지 않았거나, 지연 로딩이 활성화된 경우 전체 엔트리 대신 이를 로드합니다. 이것이 중요한 시점은 설정 및 구성을 참조하세요. 실제로는 defineSetupPluginEntry(...)를 좁은 설정 헬퍼 계열과 함께 사용하세요.
  • import-safe 설정 패치 어댑터, 조회 노트 출력, promptResolvedAllowFrom, splitSetupEntries, 위임된 설정 프록시 같은 런타임 안전 설정 헬퍼에는 openclaw/plugin-sdk/setup-runtime
  • 선택적 설치 설정 표면에는 openclaw/plugin-sdk/channel-setup
  • 설정/설치 CLI/아카이브/문서 헬퍼에는 openclaw/plugin-sdk/setup-tools
무거운 SDK, CLI 등록, 장기 실행 런타임 서비스는 전체 엔트리에 유지하세요. 설정 및 런타임 표면을 분리하는 번들 워크스페이스 채널은 대신 openclaw/plugin-sdk/channel-entry-contract의 defineBundledChannelSetupEntry(...)를 사용할 수 있습니다. 이 계약을 사용하면 설정 엔트리가 런타임 세터를 계속 노출하면서도 설정에 안전한 Plugin/시크릿 내보내기를 유지할 수 있습니다. 
import { defineBundledChannelSetupEntry } from "openclaw/plugin-sdk/channel-entry-contract";

export default defineBundledChannelSetupEntry({
  importMetaUrl: import.meta.url,
  plugin: {
    specifier: "./channel-plugin-api.js",
    exportName: "myChannelPlugin",
  },
  runtime: {
    specifier: "./runtime-api.js",
    exportName: "setMyChannelRuntime",
  },
});
전체 채널 엔트리가 로드되기 전에 설정 플로가 정말로 가벼운 런타임 세터를 필요로 하는 경우에만 이 번들 계약을 사용하세요.

​
등록 모드

api.registrationMode는 Plugin이 어떤 방식으로 로드되었는지 알려줍니다.
모드시점등록할 항목
"full"일반 Gateway 시작모든 항목
"discovery"읽기 전용 기능 검색채널 등록과 정적 CLI 설명자. 엔트리 코드는 로드될 수 있지만 소켓, 워커, 클라이언트, 서비스는 건너뜁니다
"setup-only"비활성화/미구성 채널채널 등록만
"setup-runtime"런타임을 사용할 수 있는 설정 플로전체 엔트리가 로드되기 전에 필요한 가벼운 런타임만 채널 등록과 함께 등록
"cli-metadata"루트 도움말 / CLI 메타데이터 캡처CLI 설명자만
defineChannelPluginEntry는 이 분리를 자동으로 처리합니다. 채널에 definePluginEntry를 직접 사용하는 경우 모드를 직접 확인하세요. 
register(api) {
  if (
    api.registrationMode === "cli-metadata" ||
    api.registrationMode === "discovery" ||
    api.registrationMode === "full"
  ) {
    api.registerCli(/* ... */);
    if (api.registrationMode === "cli-metadata") return;
  }

  api.registerChannel({ plugin: myPlugin });
  if (api.registrationMode !== "full") return;

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}
검색 모드는 비활성화 방식의 레지스트리 스냅샷을 빌드합니다. OpenClaw가 채널 기능과 정적 CLI 설명자를 등록할 수 있도록 Plugin 엔트리와 채널 Plugin 객체를 여전히 평가할 수 있습니다. 검색 중의 모듈 평가는 신뢰되지만 가벼운 것으로 취급하세요. 최상위에는 네트워크 클라이언트, 하위 프로세스, 리스너, 데이터베이스 연결, 백그라운드 워커, 자격 증명 읽기 또는 기타 라이브 런타임 부작용이 없어야 합니다. "setup-runtime"은 전체 번들 채널 런타임에 다시 진입하지 않고 setup-only 시작 표면이 존재해야 하는 구간으로 취급하세요. 적합한 항목은 채널 등록, 설정에 안전한 HTTP 라우트, 설정에 안전한 Gateway 메서드, 위임된 설정 헬퍼입니다. 무거운 백그라운드 서비스, CLI 등록자, 제공자/클라이언트 SDK 부트스트랩은 여전히 "full"에 속합니다. CLI 등록자에 대해서는 특히:
  • registrar가 하나 이상의 루트 명령을 소유하고 있으며 첫 호출 시 OpenClaw가 실제 CLI 모듈을 지연 로드하도록 하려면 descriptors를 사용합니다
  • 해당 설명자가 registrar가 노출하는 모든 최상위 명령 루트를 포함하는지 확인합니다
  • 설명자 명령 이름은 문자, 숫자, 하이픈, 밑줄로만 구성하고 문자 또는 숫자로 시작하도록 유지합니다. OpenClaw는 이 형식을 벗어난 설명자 이름을 거부하며, 도움말을 렌더링하기 전에 설명에서 터미널 제어 시퀀스를 제거합니다
  • 즉시 로드 호환성 경로에만 commands를 단독으로 사용합니다

​
Plugin 형태

OpenClaw는 로드된 Plugin을 등록 동작에 따라 분류합니다.
형태설명
plain-capability하나의 기능 유형(예: provider 전용)
hybrid-capability여러 기능 유형(예: provider + speech)
hook-onlyhook만 있고 기능은 없음
non-capability도구/명령/서비스는 있지만 기능은 없음
Plugin의 형태를 보려면 openclaw plugins inspect <id>를 사용합니다.

​
관련