Plugin entry points

Plugin entry points 문서는 OpenClaw 공식 문서(plugins/sdk-entrypoints)를 한국어로 정리한 가이드입니다. Reference for defineToolPlugin, definePluginEntry, defineChannelPluginEntry, and defineSetupPluginEntry 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Reference for defineToolPlugin, definePluginEntry, defineChannelPluginEntry, and defineSetupPluginEntry

한국어 가이드 범위: plugins/sdk-entrypoints 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Package entries
defineToolPlugin
definePluginEntry
defineChannelPluginEntry
defineSetupPluginEntry
Registration mode
Plugin shapes
관련 문서

상세 내용

본문

Every plugin exports a default entry object. The SDK provides a helper for each entry shape: defineToolPlugin, definePluginEntry, defineChannelPluginEntry, defineSetupPluginEntry.

Package entries

Installed plugins point package.json openclaw fields at both source and built entries:

주요 항목:

extensions and setupEntry are source entries, used for workspace and git
runtimeExtensions and runtimeSetupEntry are preferred for installed
runtimeExtensions, when present, must match extensions in array length
If a runtimeExtensions/runtimeSetupEntry artifact is declared but
If an installed package declares only a TypeScript source entry, OpenClaw
All entry paths must stay inside the plugin package directory. Runtime

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

defineToolPlugin

For plugins that only add agent tools. Keeps the source small, infers config and tool-parameter types from TypeBox schemas, wraps plain return values in the OpenClaw tool-result format, and exposes static metadata that openclaw plugins build writes into the plugin manifest (contracts.tools, configSchema).

주요 항목:

configSchema is optional; omitting it uses a strict empty object schema
execute returns a plain string or JSON-serializable value; the helper
outputSchema optionally describes that original details value for Code
For custom tool results, openclaw/plugin-sdk/tool-results exports
Tool names are static, so openclaw plugins build derives
Runtime loading stays strict: installed plugins still need

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." }),
      }),
      outputSchema: Type.Object(
        {
          symbol: Type.String(),
          hasKey: Type.Boolean(),
        },
        { additionalProperties: false },
      ),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

definePluginEntry

For provider plugins, advanced tool plugins, hook plugins, and anything that is not a messaging channel.

주요 항목:

id must match your openclaw.plugin.json manifest.
External session catalogs use
kind is deprecated: declare an exclusive slot ("memory" or
configSchema can be a function for lazy evaluation. OpenClaw resolves and
A nodeHostCommands descriptor can define isAvailable({ config, env }).

Field	Type	Required	Default
`id`	`string`	Yes	-
`name`	`string`	Yes	-
`description`	`string`	Yes	-
`kind`	`string` (deprecated, see below)	No	-
`configSchema`	`OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema`	No	Empty object schema
`reload`	`OpenClawPluginReloadRegistration`	No	-
`nodeHostCommands`	`OpenClawPluginNodeHostCommand[]`	No	-
`securityAuditCollectors`	`OpenClawPluginSecurityAuditCollector[]`	No	-
`register`	`(api: OpenClawPluginApi) => void`	Yes	-

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

defineChannelPluginEntry

Wraps definePluginEntry with channel-specific wiring: it automatically calls api.registerChannel({ plugin }), exposes an optional root-help CLI metadata seam, and gates registerFull on registration mode.

주요 항목:

setRuntime runs in every mode except "cli-metadata" and
registerCliMetadata runs for "cli-metadata", "discovery", and
registerFull runs only for "full" and "tool-discovery". For
Discovery registration is non-activating, not import-free: OpenClaw may
Like definePluginEntry, configSchema can be a lazy factory; OpenClaw
Use api.registerCli(..., { descriptors: [...] }) for plugin-owned root
Use api.registerNodeCliFeature(...) for paired-node feature commands so
For other nested plugin commands, add parentPath and register commands
For channel plugins, register CLI descriptors from registerCliMetadata
If registerFull also registers gateway RPC methods, keep them on a

Field	Type	Required	Default
`id`	`string`	Yes	-
`name`	`string`	Yes	-
`description`	`string`	Yes	-
`plugin`	`ChannelPlugin`	Yes	-
`configSchema`	`OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema`	No	Empty object schema
`setRuntime`	`(runtime: PluginRuntime) => void`	No	-
`registerCliMetadata`	`(api: OpenClawPluginApi) => void`	No	-
`registerFull`	`(api: OpenClawPluginApi) => void`	No	-

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

defineSetupPluginEntry

For the lightweight setup-entry.ts file. Returns just { plugin } with no runtime or CLI wiring.

Import	Use for
`openclaw/plugin-sdk/setup-runtime`	Runtime-safe setup helpers: `createSetupTranslator`, import-safe setup patch adapters, lookup-note output, `promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxies
`openclaw/plugin-sdk/channel-setup`	Optional-install setup surfaces
`openclaw/plugin-sdk/setup-tools`	Setup/install CLI, archive, and docs helpers

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) => {
        /* setup-safe route */
      },
    });
  },
});

Registration mode

api.registrationMode tells your plugin how it was loaded:

Mode	When	What to register
`"full"`	Normal gateway startup	Everything
`"discovery"`	Read-only capability discovery	Channel registration plus static CLI descriptors; entry code may load, but skip sockets, workers, clients, and services
`"tool-discovery"`	Scoped load to list or run specific plugins' tools	Capability/tool registration only; no channel activation
`"setup-only"`	Disabled/unconfigured channel	Channel registration only
`"setup-runtime"`	Setup flow with runtime available	Channel registration plus only the lightweight runtime needed before the full entry loads
`"cli-metadata"`	Root help / CLI metadata capture	CLI descriptors only

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") {
    // Register capability-only surfaces (providers/tools), no channel.
    return;
  }

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

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

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

Plugin shapes

OpenClaw classifies loaded plugins by their registration behavior:

Shape	Description
plain-capability	One capability type (e.g. provider-only)
hybrid-capability	Multiple capability types (e.g. provider + speech)
hook-only	Only hooks, no capabilities
non-capability	Tools/commands/services but no capabilities

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/sdk-entrypoints
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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." }),
      }),
      outputSchema: Type.Object(
        {
          symbol: Type.String(),
          hasKey: Type.Boolean(),
        },
        { additionalProperties: false },
      ),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

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

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

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) => {
        /* setup-safe route */
      },
    });
  },
});

Plugin entry points

핵심 요약

Reference for defineToolPlugin, definePluginEntry, defineChannelPluginEntry, and defineSetupPluginEntry

한국어 가이드 범위: plugins/sdk-entrypoints 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Package entries
defineToolPlugin
definePluginEntry
defineChannelPluginEntry
defineSetupPluginEntry
Registration mode
Plugin shapes
관련 문서

상세 내용

본문

Every plugin exports a default entry object. The SDK provides a helper for each entry shape: defineToolPlugin, definePluginEntry, defineChannelPluginEntry, defineSetupPluginEntry.

Package entries

Installed plugins point package.json openclaw fields at both source and built entries:

주요 항목:

extensions and setupEntry are source entries, used for workspace and git
runtimeExtensions and runtimeSetupEntry are preferred for installed
runtimeExtensions, when present, must match extensions in array length
If a runtimeExtensions/runtimeSetupEntry artifact is declared but
If an installed package declares only a TypeScript source entry, OpenClaw
All entry paths must stay inside the plugin package directory. Runtime

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

defineToolPlugin

주요 항목:

configSchema is optional; omitting it uses a strict empty object schema
execute returns a plain string or JSON-serializable value; the helper
outputSchema optionally describes that original details value for Code
For custom tool results, openclaw/plugin-sdk/tool-results exports
Tool names are static, so openclaw plugins build derives
Runtime loading stays strict: installed plugins still need

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." }),
      }),
      outputSchema: Type.Object(
        {
          symbol: Type.String(),
          hasKey: Type.Boolean(),
        },
        { additionalProperties: false },
      ),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

definePluginEntry

For provider plugins, advanced tool plugins, hook plugins, and anything that is not a messaging channel.

주요 항목:

id must match your openclaw.plugin.json manifest.
External session catalogs use
kind is deprecated: declare an exclusive slot ("memory" or
configSchema can be a function for lazy evaluation. OpenClaw resolves and
A nodeHostCommands descriptor can define isAvailable({ config, env }).

Field	Type	Required	Default
`id`	`string`	Yes	-
`name`	`string`	Yes	-
`description`	`string`	Yes	-
`kind`	`string` (deprecated, see below)	No	-
`configSchema`	`OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema`	No	Empty object schema
`reload`	`OpenClawPluginReloadRegistration`	No	-
`nodeHostCommands`	`OpenClawPluginNodeHostCommand[]`	No	-
`securityAuditCollectors`	`OpenClawPluginSecurityAuditCollector[]`	No	-
`register`	`(api: OpenClawPluginApi) => void`	Yes	-

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

defineChannelPluginEntry

주요 항목:

setRuntime runs in every mode except "cli-metadata" and
registerCliMetadata runs for "cli-metadata", "discovery", and
registerFull runs only for "full" and "tool-discovery". For
Discovery registration is non-activating, not import-free: OpenClaw may
Like definePluginEntry, configSchema can be a lazy factory; OpenClaw
Use api.registerCli(..., { descriptors: [...] }) for plugin-owned root
Use api.registerNodeCliFeature(...) for paired-node feature commands so
For other nested plugin commands, add parentPath and register commands
For channel plugins, register CLI descriptors from registerCliMetadata
If registerFull also registers gateway RPC methods, keep them on a

Field	Type	Required	Default
`id`	`string`	Yes	-
`name`	`string`	Yes	-
`description`	`string`	Yes	-
`plugin`	`ChannelPlugin`	Yes	-
`configSchema`	`OpenClawPluginConfigSchema \| () => OpenClawPluginConfigSchema`	No	Empty object schema
`setRuntime`	`(runtime: PluginRuntime) => void`	No	-
`registerCliMetadata`	`(api: OpenClawPluginApi) => void`	No	-
`registerFull`	`(api: OpenClawPluginApi) => void`	No	-

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

defineSetupPluginEntry

For the lightweight setup-entry.ts file. Returns just { plugin } with no runtime or CLI wiring.

Import	Use for
`openclaw/plugin-sdk/setup-runtime`	Runtime-safe setup helpers: `createSetupTranslator`, import-safe setup patch adapters, lookup-note output, `promptResolvedAllowFrom`, `splitSetupEntries`, delegated setup proxies
`openclaw/plugin-sdk/channel-setup`	Optional-install setup surfaces
`openclaw/plugin-sdk/setup-tools`	Setup/install CLI, archive, and docs helpers

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) => {
        /* setup-safe route */
      },
    });
  },
});

Registration mode

api.registrationMode tells your plugin how it was loaded:

Mode	When	What to register
`"full"`	Normal gateway startup	Everything
`"discovery"`	Read-only capability discovery	Channel registration plus static CLI descriptors; entry code may load, but skip sockets, workers, clients, and services
`"tool-discovery"`	Scoped load to list or run specific plugins' tools	Capability/tool registration only; no channel activation
`"setup-only"`	Disabled/unconfigured channel	Channel registration only
`"setup-runtime"`	Setup flow with runtime available	Channel registration plus only the lightweight runtime needed before the full entry loads
`"cli-metadata"`	Root help / CLI metadata capture	CLI descriptors only

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") {
    // Register capability-only surfaces (providers/tools), no channel.
    return;
  }

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

  // Heavy runtime-only registrations
  api.registerService(/* ... */);
}

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

Plugin shapes

OpenClaw classifies loaded plugins by their registration behavior:

Shape	Description
plain-capability	One capability type (e.g. provider-only)
hybrid-capability	Multiple capability types (e.g. provider + speech)
hook-only	Only hooks, no capabilities
non-capability	Tools/commands/services but no capabilities

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/plugins/sdk-entrypoints
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

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

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." }),
      }),
      outputSchema: Type.Object(
        {
          symbol: Type.String(),
          hasKey: Type.Boolean(),
        },
        { additionalProperties: false },
      ),
      execute: async ({ symbol }, config) => ({ symbol, hasKey: Boolean(config.apiKey) }),
    }),
  ],
});

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

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

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) => {
        /* setup-safe route */
      },
    });
  },
});

Plugin entry points

핵심 요약

문서 구성

상세 내용

본문

Package entries

defineToolPlugin

definePluginEntry

defineChannelPluginEntry

defineSetupPluginEntry

Registration mode

Plugin shapes

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Plugin entry points

핵심 요약

문서 구성

상세 내용

본문

Package entries

defineToolPlugin

definePluginEntry

defineChannelPluginEntry

defineSetupPluginEntry

Registration mode

Plugin shapes

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드