Building plugins

Building plugins 문서는 OpenClaw 공식 문서(plugins/building-plugins)를 한국어로 정리한 가이드입니다. Create your first OpenClaw plugin in minutes 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Create your first OpenClaw plugin in minutes

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

문서 구성

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

요구사항
Choose the plugin shape
Quickstart
Registering tools
Import conventions
Pre-submission checklist
Test against beta releases
다음 단계
관련 문서

상세 내용

본문

Plugins extend OpenClaw without changing core. A plugin can add a messaging channel, model provider, local CLI backend, agent tool, hook, media provider, or another plugin-owned capability.

openclaw plugins install clawhub:<package-name>

요구사항

Source-checkout plugin development is pnpm-only because OpenClaw discovers bundled plugins from extensions/* workspace packages.

주요 항목:

Node 22.22.3+, Node 24.15+, or Node 25.9+, and npm or pnpm.
TypeScript ESM modules.
For in-repo bundled plugin work, clone the repository and run pnpm install.

Choose the plugin shape

Connect OpenClaw to a messaging platform.

Quickstart

Build a minimal tool plugin by registering one required agent tool. This is the shortest useful plugin shape and covers the package, manifest, entry point, and local proof.

Published external plugins should point runtime entries at built JavaScript
    files. See [SDK entry points](/plugins/sdk-entrypoints) for the full entry
    point contract.

    Every plugin needs a manifest, even with no config. Runtime tools must
    appear in `contracts.tools` so OpenClaw can discover ownership without
    eagerly loading every plugin runtime. Set `activation.onStartup`
    intentionally; this example loads on Gateway startup.

    Host-trusted plugin surfaces are manifest-gated too and require explicit
    declaration for installed plugins: `api.registerAgentToolResultMiddleware(...)`
    needs each target runtime listed in `contracts.agentToolResultMiddleware`,
    and `api.registerTrustedToolPolicy(...)` needs each policy id in
    `contracts.trustedToolPolicies`. These declarations keep install-time
    inspection and runtime registration aligned.

    For every manifest field, see [Plugin manifest](/plugins/manifest).

Use `definePluginEntry` for non-channel plugins. Channel plugins use
    `defineChannelPluginEntry` from `openclaw/plugin-sdk/core` instead.

  

  

    For an installed or external plugin, inspect the loaded runtime:

If the plugin registers a CLI command, run that command too and confirm
    output, for example `openclaw demo-plugin ping`.

    For a bundled plugin in this repository, OpenClaw discovers source-checkout
    plugin packages from the `extensions/*` workspace. Run the closest targeted
    test:

Registering tools

Tools can be required or optional. Required tools are always available when the plugin is enabled. Optional tools need explicit user opt-in before OpenClaw loads the owning plugin runtime.

register(api) {
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      outputSchema: Type.Object(
        { pipeline: Type.String() },
        { additionalProperties: false },
      ),
      async execute(_id, params) {
        return {
          content: [{ type: "text", text: params.pipeline }],
          details: { pipeline: params.pipeline },
        };
      },
    },
    { optional: true },
  );
}

{
  "contracts": {
    "tools": ["workflow_tool"]
  },
  "toolMetadata": {
    "workflow_tool": {
      "optional": true
    }
  }
}

{
  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin
}

Import conventions

Within your plugin package, use local barrel files such as api.ts and runtime-api.ts for internal imports. Do not import your own plugin through an SDK path. Provider-specific helpers should stay in the provider package unless the seam is truly generic.

Pre-submission checklist

Entry point uses defineChannelPluginEntry or definePluginEntry

Test against beta releases

Watch openclaw/openclaw releases (Watch > Releases). Beta tags look like v2026.3.N-beta.1. You can also follow @openclaw on X for release announcements. 2. Test your plugin against the beta tag as soon as it appears. The window before stable is typically only a few hours. 3. Post in your plugin's thread in the plugin-forum Discord channel (discord.gg/clawd) after testing, with either all good or what broke. Create a thread if you do not have one yet. 4. If something breaks, open or update an issue titled Beta blocker: - and apply the beta-blocker label. Link the issue in your thread. 5. Open a PR to main titled fix(): beta blocker - and link the issue in both the PR and your Discord thread. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation. Blockers with a PR get merged; blockers without one might ship anyway. 6. Silence means green. Missing the window usually means your fix lands in the next cycle.

다음 단계

Import map and registration API reference

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw plugins install clawhub:<package-name>

Published external plugins should point runtime entries at built JavaScript
    files. See [SDK entry points](/plugins/sdk-entrypoints) for the full entry
    point contract.

    Every plugin needs a manifest, even with no config. Runtime tools must
    appear in `contracts.tools` so OpenClaw can discover ownership without
    eagerly loading every plugin runtime. Set `activation.onStartup`
    intentionally; this example loads on Gateway startup.

    Host-trusted plugin surfaces are manifest-gated too and require explicit
    declaration for installed plugins: `api.registerAgentToolResultMiddleware(...)`
    needs each target runtime listed in `contracts.agentToolResultMiddleware`,
    and `api.registerTrustedToolPolicy(...)` needs each policy id in
    `contracts.trustedToolPolicies`. These declarations keep install-time
    inspection and runtime registration aligned.

    For every manifest field, see [Plugin manifest](/plugins/manifest).

Use `definePluginEntry` for non-channel plugins. Channel plugins use
    `defineChannelPluginEntry` from `openclaw/plugin-sdk/core` instead.

  

  

    For an installed or external plugin, inspect the loaded runtime:

If the plugin registers a CLI command, run that command too and confirm
    output, for example `openclaw demo-plugin ping`.

    For a bundled plugin in this repository, OpenClaw discovers source-checkout
    plugin packages from the `extensions/*` workspace. Run the closest targeted
    test:

Before publishing a package-ready plugin, test the same install shape users
    will get. First add a build step, point runtime entries such as
    `openclaw.extensions` at built JavaScript like `./dist/index.js`, and make
    sure `npm pack` includes that `dist/` output. TypeScript source entries are
    only for source checkouts and local development paths.

    Then pack the plugin and install the tarball with `npm-pack:`:

Building plugins

핵심 요약

Create your first OpenClaw plugin in minutes

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

문서 구성

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

요구사항
Choose the plugin shape
Quickstart
Registering tools
Import conventions
Pre-submission checklist
Test against beta releases
다음 단계
관련 문서

상세 내용

본문

Plugins extend OpenClaw without changing core. A plugin can add a messaging channel, model provider, local CLI backend, agent tool, hook, media provider, or another plugin-owned capability.

openclaw plugins install clawhub:<package-name>

요구사항

Source-checkout plugin development is pnpm-only because OpenClaw discovers bundled plugins from extensions/* workspace packages.

주요 항목:

Node 22.22.3+, Node 24.15+, or Node 25.9+, and npm or pnpm.
TypeScript ESM modules.
For in-repo bundled plugin work, clone the repository and run pnpm install.

Choose the plugin shape

Connect OpenClaw to a messaging platform.

Quickstart

Build a minimal tool plugin by registering one required agent tool. This is the shortest useful plugin shape and covers the package, manifest, entry point, and local proof.

Published external plugins should point runtime entries at built JavaScript
    files. See [SDK entry points](/plugins/sdk-entrypoints) for the full entry
    point contract.

    Every plugin needs a manifest, even with no config. Runtime tools must
    appear in `contracts.tools` so OpenClaw can discover ownership without
    eagerly loading every plugin runtime. Set `activation.onStartup`
    intentionally; this example loads on Gateway startup.

    Host-trusted plugin surfaces are manifest-gated too and require explicit
    declaration for installed plugins: `api.registerAgentToolResultMiddleware(...)`
    needs each target runtime listed in `contracts.agentToolResultMiddleware`,
    and `api.registerTrustedToolPolicy(...)` needs each policy id in
    `contracts.trustedToolPolicies`. These declarations keep install-time
    inspection and runtime registration aligned.

    For every manifest field, see [Plugin manifest](/plugins/manifest).

Use `definePluginEntry` for non-channel plugins. Channel plugins use
    `defineChannelPluginEntry` from `openclaw/plugin-sdk/core` instead.

  

  

    For an installed or external plugin, inspect the loaded runtime:

If the plugin registers a CLI command, run that command too and confirm
    output, for example `openclaw demo-plugin ping`.

    For a bundled plugin in this repository, OpenClaw discovers source-checkout
    plugin packages from the `extensions/*` workspace. Run the closest targeted
    test:

Registering tools

Tools can be required or optional. Required tools are always available when the plugin is enabled. Optional tools need explicit user opt-in before OpenClaw loads the owning plugin runtime.

register(api) {
  api.registerTool(
    {
      name: "workflow_tool",
      description: "Run a workflow",
      parameters: Type.Object({ pipeline: Type.String() }),
      outputSchema: Type.Object(
        { pipeline: Type.String() },
        { additionalProperties: false },
      ),
      async execute(_id, params) {
        return {
          content: [{ type: "text", text: params.pipeline }],
          details: { pipeline: params.pipeline },
        };
      },
    },
    { optional: true },
  );
}

{
  "contracts": {
    "tools": ["workflow_tool"]
  },
  "toolMetadata": {
    "workflow_tool": {
      "optional": true
    }
  }
}

{
  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for every tool from one plugin
}

Import conventions

Pre-submission checklist

Entry point uses defineChannelPluginEntry or definePluginEntry

Test against beta releases

Watch openclaw/openclaw releases (Watch > Releases). Beta tags look like v2026.3.N-beta.1. You can also follow @openclaw on X for release announcements. 2. Test your plugin against the beta tag as soon as it appears. The window before stable is typically only a few hours. 3. Post in your plugin's thread in the plugin-forum Discord channel (discord.gg/clawd) after testing, with either all good or what broke. Create a thread if you do not have one yet. 4. If something breaks, open or update an issue titled Beta blocker: - and apply the beta-blocker label. Link the issue in your thread. 5. Open a PR to main titled fix(): beta blocker - and link the issue in both the PR and your Discord thread. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation. Blockers with a PR get merged; blockers without one might ship anyway. 6. Silence means green. Missing the window usually means your fix lands in the next cycle.

다음 단계

Import map and registration API reference

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw plugins install clawhub:<package-name>

Published external plugins should point runtime entries at built JavaScript
    files. See [SDK entry points](/plugins/sdk-entrypoints) for the full entry
    point contract.

    Every plugin needs a manifest, even with no config. Runtime tools must
    appear in `contracts.tools` so OpenClaw can discover ownership without
    eagerly loading every plugin runtime. Set `activation.onStartup`
    intentionally; this example loads on Gateway startup.

    Host-trusted plugin surfaces are manifest-gated too and require explicit
    declaration for installed plugins: `api.registerAgentToolResultMiddleware(...)`
    needs each target runtime listed in `contracts.agentToolResultMiddleware`,
    and `api.registerTrustedToolPolicy(...)` needs each policy id in
    `contracts.trustedToolPolicies`. These declarations keep install-time
    inspection and runtime registration aligned.

    For every manifest field, see [Plugin manifest](/plugins/manifest).

Use `definePluginEntry` for non-channel plugins. Channel plugins use
    `defineChannelPluginEntry` from `openclaw/plugin-sdk/core` instead.

  

  

    For an installed or external plugin, inspect the loaded runtime:

If the plugin registers a CLI command, run that command too and confirm
    output, for example `openclaw demo-plugin ping`.

    For a bundled plugin in this repository, OpenClaw discovers source-checkout
    plugin packages from the `extensions/*` workspace. Run the closest targeted
    test:

Before publishing a package-ready plugin, test the same install shape users
    will get. First add a build step, point runtime entries such as
    `openclaw.extensions` at built JavaScript like `./dist/index.js`, and make
    sure `npm pack` includes that `dist/` output. TypeScript source entries are
    only for source checkouts and local development paths.

    Then pack the plugin and install the tarball with `npm-pack:`:

Building plugins

핵심 요약

문서 구성

상세 내용

본문

요구사항

Choose the plugin shape

Quickstart

Registering tools

Import conventions

Pre-submission checklist

Test against beta releases

다음 단계

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Building plugins

핵심 요약

문서 구성

상세 내용

본문

요구사항

Choose the plugin shape

Quickstart

Registering tools

Import conventions

Pre-submission checklist

Test against beta releases

다음 단계

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드