Building Plugins

plugin은 OpenClaw에 새로운 capability를 추가합니다: channel, model provider, speech, image generation, web search, agent tool, 또는 그 조합입니다. plugin을 OpenClaw 저장소에 직접 추가할 필요는 없습니다. ClawHub 또는 npm에 publish하면 사용자는 openclaw plugins install <package-name>으로 설치할 수 있습니다. OpenClaw는 먼저 ClawHub를 확인하고, 없으면 npm으로 fallback합니다.

필요 조건

Node >= 22 및 package manager(npm 또는 pnpm)
TypeScript(ESM) 기본 이해
저장소 내부 plugin이라면 repository clone + pnpm install

어떤 종류의 plugin인가

Channel plugin

OpenClaw를 새로운 메시징 플랫폼(Discord, IRC 등)에 연결

Provider plugin

새로운 모델 provider(LLM, proxy, custom endpoint) 추가

Tool / hook plugin

agent tool, event hook, service 등록

빠른 시작: tool plugin

최소 plugin 하나를 만들어 agent tool을 등록하는 예시입니다.

패키지와 manifest 만들기

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"]
  }
}

{
  "id": "my-plugin",
  "name": "My Plugin",
  "description": "Adds a custom tool to OpenClaw",
  "configSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

config가 없어도 manifest는 필요합니다. 전체 스키마는 Manifest를 보세요.

entry point 작성

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { Type } from "@sinclair/typebox";

export default definePluginEntry({
  id: "my-plugin",
  name: "My Plugin",
  description: "Adds a custom tool to OpenClaw",
  register(api) {
    api.registerTool({
      name: "my_tool",
      description: "Do a thing",
      parameters: Type.Object({ input: Type.String() }),
      async execute(_id, params) {
        return { content: [{ type: "text", text: `Got: ${params.input}` }] };
      },
    });
  },
});

definePluginEntry는 non-channel plugin용입니다. channel은 defineChannelPluginEntry를 사용하세요.

테스트와 배포

외부 plugin은 ClawHub 또는 npm에 publish한 뒤 설치합니다:

openclaw plugins install @myorg/openclaw-my-plugin

저장소 내부 plugin은 extensions/ 아래에 두면 자동 감지됩니다.

pnpm test -- extensions/my-plugin/

Plugin capability

하나의 plugin은 api 객체를 통해 여러 capability를 등록할 수 있습니다:

Capability	Registration method	Detailed guide
Text inference (LLM)	`api.registerProvider(...)`	Provider Plugins
Channel / messaging	`api.registerChannel(...)`	Channel Plugins
Speech (TTS/STT)	`api.registerSpeechProvider(...)`	Provider Plugins
Media understanding	`api.registerMediaUnderstandingProvider(...)`	Provider Plugins
Image generation	`api.registerImageGenerationProvider(...)`	Provider Plugins
Web search	`api.registerWebSearchProvider(...)`	Provider Plugins
Agent tools	`api.registerTool(...)`	아래 설명
Event hooks	`api.registerHook(...)`	Entry Points
HTTP routes	`api.registerHttpRoute(...)`	Internals
CLI subcommands	`api.registerCli(...)`	Entry Points

Agent tool 등록

tool은 LLM이 호출할 수 있는 typed function입니다. 항상 사용 가능한 필수 tool도 있고, 사용자가 allowlist로 켜야 하는 optional tool도 있습니다.

register(api) {
  api.registerTool({
    name: "my_tool",
    description: "Do a thing",
    parameters: Type.Object({ input: Type.String() }),
    async execute(_id, params) {
      return { content: [{ type: "text", text: params.input }] };
    },
  });

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

사용자는 config에서 optional tool을 켭니다:

{
  tools: { allow: ["workflow_tool"] },
}

Import 규칙

항상 openclaw/plugin-sdk/<subpath>의 좁은 경로에서 import하세요:

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";

plugin 내부 import는 로컬 barrel 파일(api.ts, runtime-api.ts)로 정리하고, 자기 plugin을 SDK 경로로 다시 import하지 마세요.

제출 전 체크리스트

package.json에 올바른 openclaw metadata가 있는가

openclaw.plugin.json manifest가 유효한가

entry point가 defineChannelPluginEntry 또는 definePluginEntry를 쓰는가

import가 모두 plugin-sdk/<subpath>를 쓰는가

테스트가 통과하는가

Overview

Built-in tools

Browser

Agent coordination

Skills

Extensions

Automation

Media and devices

Building Plugins

Building Plugins

필요 조건

어떤 종류의 plugin인가

Channel plugin

Provider plugin

Tool / hook plugin

빠른 시작: tool plugin

Plugin capability

Agent tool 등록

Import 규칙

제출 전 체크리스트

다음 단계

​Building Plugins

​필요 조건

​어떤 종류의 plugin인가

Channel plugin

Provider plugin

Tool / hook plugin

​빠른 시작: tool plugin

​Plugin capability

​Agent tool 등록

​Import 규칙

​제출 전 체크리스트

​다음 단계

Building Plugins

필요 조건

어떤 종류의 plugin인가

빠른 시작: tool plugin

Plugin capability

Agent tool 등록

Import 규칙

제출 전 체크리스트

다음 단계