메인 콘텐츠로 건너뛰기

​
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을 등록하는 예시입니다.
1

패키지와 manifest 만들기

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"]
  }
}
config가 없어도 manifest는 필요합니다. 전체 스키마는 Manifest를 보세요.
2

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를 사용하세요.
3

테스트와 배포

외부 plugin은 ClawHub 또는 npm에 publish한 뒤 설치합니다:
openclaw plugins install @myorg/openclaw-my-plugin
저장소 내부 plugin은 extensions/ 아래에 두면 자동 감지됩니다.
pnpm test -- extensions/my-plugin/

​
Plugin capability

하나의 plugin은 api 객체를 통해 여러 capability를 등록할 수 있습니다:
CapabilityRegistration methodDetailed guide
Text inference (LLM)api.registerProvider(...)Provider Plugins
Channel / messagingapi.registerChannel(...)Channel Plugins
Speech (TTS/STT)api.registerSpeechProvider(...)Provider Plugins
Media understandingapi.registerMediaUnderstandingProvider(...)Provider Plugins
Image generationapi.registerImageGenerationProvider(...)Provider Plugins
Web searchapi.registerWebSearchProvider(...)Provider Plugins
Agent toolsapi.registerTool(...)아래 설명
Event hooksapi.registerHook(...)Entry Points
HTTP routesapi.registerHttpRoute(...)Internals
CLI subcommandsapi.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>를 쓰는가
테스트가 통과하는가

​
다음 단계