​

Building Plugins

​

전제 조건

• Node >= 22 및 패키지 관리자(npm 또는 pnpm)
• TypeScript(ESM)에 대한 익숙함
• 리포지토리 내부 plugin의 경우: 리포지토리 클론 및 pnpm install 완료

​

어떤 종류의 plugin인가요?

​

빠른 시작: 도구 plugin

{
  "name": "@myorg/openclaw-my-plugin",
  "version": "1.0.0",
  "type": "module",
  "openclaw": {
    "extensions": ["./index.ts"],
    "compat": {
      "pluginApi": ">=2026.3.24-beta.2",
      "minGatewayVersion": "2026.3.24-beta.2"
    },
    "build": {
      "openclawVersion": "2026.3.24-beta.2",
      "pluginSdkVersion": "2026.3.24-beta.2"
    }
  }
}

// index.ts
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}` }] };
      },
    });
  },
});

clawhub package publish your-org/your-plugin --dry-run
clawhub package publish your-org/your-plugin
openclaw plugins install clawhub:@myorg/openclaw-my-plugin

pnpm test -- <bundled-plugin-root>/my-plugin/

​

Plugin 기능

• before_tool_call: { block: true }는 최종 결정이며 더 낮은 우선순위 핸들러를 중단시킵니다.
• before_tool_call: { block: false }는 결정 없음으로 처리됩니다.
• before_tool_call: { requireApproval: true }는 에이전트 실행을 일시 중지하고 exec 승인 오버레이, Telegram 버튼, Discord 상호작용 또는 어느 채널에서든 /approve 명령을 통해 사용자 승인을 요청합니다.
• before_install: { block: true }는 최종 결정이며 더 낮은 우선순위 핸들러를 중단시킵니다.
• before_install: { block: false }는 결정 없음으로 처리됩니다.
• message_sending: { cancel: true }는 최종 결정이며 더 낮은 우선순위 핸들러를 중단시킵니다.
• message_sending: { cancel: false }는 결정 없음으로 처리됩니다.

​

에이전트 도구 등록

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 },
  );
}

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

• 도구 이름은 코어 도구와 충돌하면 안 됩니다(충돌 시 건너뜀)
• 부작용이나 추가 바이너리 요구 사항이 있는 도구에는 optional: true를 사용하세요
• 사용자는 tools.allow에 plugin ID를 추가하여 plugin의 모든 도구를 활성화할 수 있습니다

​

import 규칙

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

// 잘못된 예: 단일 루트(monolithic root, deprecated, 추후 제거 예정)
import { ... } from "openclaw/plugin-sdk";

• Anthropic: Claude 스트림 래퍼 및 service_tier / 베타 helper
• OpenAI: provider 빌더, 기본 모델 helper, 실시간 provider
• OpenRouter: provider 빌더 및 onboarding/config helper

​

제출 전 체크리스트

​

베타 릴리스 테스트

1. openclaw/openclaw의 GitHub 릴리스 태그를 주시하고 Watch > Releases를 통해 구독하세요. 베타 태그는 v2026.3.N-beta.1처럼 보입니다. 릴리스 공지를 위해 공식 OpenClaw X 계정 @openclaw의 알림을 켤 수도 있습니다.
2. 베타 태그가 나타나는 즉시 plugin을 테스트하세요. stable 이전의 창은 보통 몇 시간밖에 되지 않습니다.
3. 테스트 후 plugin-forum Discord 채널의 plugin 스레드에 all good 또는 무엇이 깨졌는지를 게시하세요. 아직 스레드가 없다면 새로 만드세요.
4. 무언가 깨졌다면 Beta blocker: <plugin-name> - <summary> 제목으로 이슈를 열거나 업데이트하고 beta-blocker 레이블을 적용하세요. 이슈 링크를 스레드에 넣으세요.
5. main에 fix(<plugin-id>): beta blocker - <summary> 제목으로 PR을 열고, PR과 Discord 스레드 모두에 이슈를 링크하세요. 기여자는 PR에 레이블을 붙일 수 없으므로 제목이 유지관리자와 자동화를 위한 PR 측 신호입니다. PR이 있는 blocker는 병합되고, 없는 blocker는 그대로 릴리스될 수 있습니다. 유지관리자는 베타 테스트 동안 이 스레드를 모니터링합니다.
6. 아무 말이 없으면 녹색 신호입니다. 시간을 놓쳤다면 수정 사항은 다음 주기에 들어갈 가능성이 큽니다.

​

다음 단계

​

관련

• Plugin Architecture — 내부 아키텍처 심층 설명
• SDK Overview — Plugin SDK 참조
• Manifest — plugin manifest 형식
• Channel Plugins — 채널 plugin 만들기
• Provider Plugins — provider plugin 만들기