Plugin 빌드하기

Plugin은 core를 변경하지 않고 OpenClaw를 확장합니다. Plugin은 메시징 채널, 모델 공급자, 로컬 CLI 백엔드, 에이전트 도구, 훅, 미디어 공급자 또는 다른 Plugin 소유 기능을 추가할 수 있습니다.

외부 Plugin을 OpenClaw 리포지토리에 추가할 필요는 없습니다. 패키지를 ClawHub에 게시하면 사용자는 다음으로 설치합니다.

openclaw plugins install clawhub:<package-name>

베어 패키지 사양은 출시 전환 기간 동안 계속 npm에서 설치됩니다. ClawHub 해석을 원할 때는 clawhub: 접두사를 사용하세요.

요구 사항

• Node 22.19+, Node 23.11+ 또는 Node 24+와 npm 또는 pnpm 같은 패키지 관리자를 사용하세요.
• TypeScript ESM 모듈에 익숙해야 합니다.
• 리포지토리 내 번들 Plugin 작업의 경우 리포지토리를 클론하고 pnpm install을 실행하세요. OpenClaw가 extensions/* 워크스페이스 패키지에서 번들 Plugin을 로드하므로 소스 체크아웃 Plugin 개발은 pnpm 전용입니다.

Plugin 형태 선택

빠른 시작

필수 에이전트 도구 하나를 등록하여 최소 도구 Plugin을 빌드합니다. 이는 가장 짧고 유용한 Plugin 형태이며 패키지, 매니페스트, 진입점, 로컬 증명을 보여줍니다.

{"name": "@myorg/openclaw-my-plugin","version": "1.0.0","type": "module","dependencies": {"typebox": "1.1.39"},"peerDependencies": {"openclaw": ">=2026.3.24-beta.2"},"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"}}}

{"id": "my-plugin","name": "My Plugin","description": "Adds a custom tool to OpenClaw","contracts": {"tools": ["my_tool"]},"activation": {"onStartup": true},"configSchema": {"type": "object","additionalProperties": false}}

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

openclaw plugins inspect my-plugin --runtime --json

pnpm test -- extensions/my-plugin/pnpm check

npm pack --pack-destination /tmpopenclaw plugins install npm-pack:/tmp/<plugin-package>.tgz --forceopenclaw plugins inspect my-plugin --runtime --json

clawhub package publish your-org/your-plugin --dry-runclawhub package publish your-org/your-plugin

openclaw plugins install clawhub:your-org/your-plugin

도구 등록

도구는 필수 또는 선택 사항일 수 있습니다. 필수 도구는 Plugin이 활성화되면 항상 사용할 수 있습니다. 선택 도구는 사용자의 명시적 동의가 필요합니다.

register(api) {  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 },  );}

api.registerTool(...)로 등록된 모든 도구는 Plugin 매니페스트에도 선언되어야 합니다.

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

사용자는 tools.allow로 선택합니다.

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

선택 도구는 도구가 모델에 노출되는지 여부를 제어합니다. 도구나 훅이 모델이 선택한 뒤 작업이 실행되기 전에 승인을 요청해야 하는 경우 Plugin 권한 요청을 사용하세요.

부작용, 특수한 바이너리 또는 기본적으로 노출되어서는 안 되는 기능에는 선택 도구를 사용하세요. 도구 이름은 core 도구와 충돌해서는 안 됩니다. 충돌은 건너뛰고 Plugin 진단에 보고됩니다. parameters가 없는 도구 설명자 등 잘못된 등록도 같은 방식으로 건너뛰고 보고됩니다. 등록된 도구는 정책과 허용 목록 검사를 통과한 뒤 모델이 호출할 수 있는 타입이 지정된 함수입니다.

도구 팩토리는 런타임에서 제공하는 컨텍스트 객체를 받습니다. 도구가 현재 턴의 활성 모델을 기록, 표시 또는 이에 맞춰 조정해야 할 때 ctx.activeModel을 사용하세요. 이 객체에는 provider, modelId, modelRef가 포함될 수 있습니다. 이를 로컬 운영자, 설치된 Plugin 코드 또는 수정된 OpenClaw 런타임에 대한 보안 경계가 아니라 정보성 런타임 메타데이터로 취급하세요. 민감한 로컬 도구는 여전히 명시적 Plugin 또는 운영자 opt-in을 요구해야 하며, 활성 모델 메타데이터가 없거나 적합하지 않으면 닫힌 상태로 실패해야 합니다.

매니페스트는 소유권과 발견을 선언하며, 실행은 여전히 라이브 등록 도구 구현을 호출합니다. toolMetadata.<tool>.optional: true를 api.registerTool(..., { optional: true })와 일치시켜 OpenClaw가 도구가 명시적으로 허용 목록에 추가될 때까지 해당 Plugin 런타임을 로드하지 않도록 하세요.

Import 규칙

집중된 SDK 하위 경로에서 import하세요.

사용 중단된 루트 배럴에서 import하지 마세요.

Plugin 패키지 내부에서는 내부 import에 api.ts 및 runtime-api.ts 같은 로컬 배럴 파일을 사용하세요. 자체 Plugin을 SDK 경로를 통해 import하지 마세요. 공급자별 헬퍼는 경계가 진정으로 범용적이지 않은 한 공급자 패키지에 남겨두어야 합니다.

사용자 지정 Gateway RPC 메서드는 고급 진입점입니다. Plugin별 접두사에 유지하세요. config.*, exec.approvals.*, operator.admin.*, wizard.*, update.* 같은 core 관리자 네임스페이스는 예약되어 있으며 operator.admin으로 해석됩니다. openclaw/plugin-sdk/gateway-method-runtime 브리지는 contracts.gatewayMethodDispatch: ["authenticated-request"]를 선언하는 Plugin HTTP 라우트 전용으로 예약되어 있습니다.

전체 import 맵은 Plugin SDK 개요를 참조하세요.

제출 전 체크리스트

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s package.json에 올바른 openclaw 메타데이터가 있음 OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s openclaw.plugin.json 매니페스트가 존재하고 유효함 OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s 진입점이 defineChannelPluginEntry 또는 definePluginEntry를 사용함 OPENCLAW_DOCS_MARKER:calloutClose:

OPENCLAW_DOCS_MARKER:calloutOpen:Q2hlY2s 모든 import가 집중된 plugin-sdk/<subpath> 경로를 사용함 OPENCLAW_DOCS_MARKER:calloutClose: