Plugin 빌드하기

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

외부 Plugin을 OpenClaw 저장소에 추가할 필요는 없습니다. 패키지를 ClawHub에 게시하면 사용자는 다음 명령으로 설치할 수 있습니다.

openclaw plugins install clawhub:<package-name>

출시 전환 기간에는 접두사 없는 패키지 사양도 계속 npm에서 설치됩니다. ClawHub에서 해석하려면 clawhub: 접두사를 사용하십시오.

요구 사항

• Node 22.22.3+, Node 24.15+ 또는 Node 25.9+ 및 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": "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이 활성화되면 항상 사용할 수 있습니다. 선택적 도구는 OpenClaw가 해당 도구를 소유한 Plugin 런타임을 로드하기 전에 사용자가 명시적으로 동의해야 합니다.

도구 팩터리는 신뢰할 수 있는 런타임 컨텍스트를 받으며, 여기에는 deliveryContext, 사용 가능한 경우 활성 플랫폼 대화를 위한 nativeChannelId, 그리고 requesterSenderId이 포함됩니다.

register(api) {  api.registerTool(    {      name: "workflow_tool",      description: "워크플로 실행",      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"] }, // 또는 한 Plugin의 모든 도구에는 ["my-plugin"]}

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

부작용이 있거나, 일반적이지 않은 바이너리가 필요하거나, 기본적으로 노출해서는 안 되는 기능에는 선택적 도구를 사용하십시오. 도구 이름은 핵심 도구 이름과 충돌해서는 안 됩니다. 충돌하는 등록은 건너뛰고 Plugin 진단에 보고됩니다. 잘못된 형식의 등록도 같은 방식으로 건너뛰고 보고됩니다. 여기에는 비어 있지 않은 name의 누락, 함수가 아닌 execute, 또는 parameters 객체가 없는 도구 설명자가 포함됩니다.

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

매니페스트는 소유권과 검색을 선언하지만, 실행 시에는 여전히 등록된 실제 도구 구현을 호출합니다. OpenClaw가 도구가 명시적으로 허용 목록에 추가될 때까지 해당 Plugin 런타임을 로드하지 않을 수 있도록 toolMetadata.<tool>.optional: true을 api.registerTool(..., { optional: true })과 일치하게 유지하십시오.

가져오기 규칙

세분화된 SDK 하위 경로에서 가져오십시오.

사용 중단된 루트 배럴에서 가져오지 마십시오.

Plugin 패키지 내에서는 내부 가져오기에 api.ts 및 runtime-api.ts 같은 로컬 배럴 파일을 사용하십시오. SDK 경로를 통해 자체 Plugin을 가져오지 마십시오. 프로바이더별 헬퍼는 경계가 실제로 일반적인 경우가 아니라면 프로바이더 패키지에 유지해야 합니다.

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

전체 가져오기 맵은 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 모든 가져오기에 세분화된 plugin-sdk/<subpath> 경로를 사용합니다 OPENCLAW_DOCS_MARKER:calloutClose: