Plugin 설정 및 구성

Plugin 패키징(package.json 메타데이터), 매니페스트(openclaw.plugin.json), 설정 엔트리 및 구성 스키마에 대한 참고 자료입니다.

패키지 메타데이터

package.json에는 Plugin 시스템에 Plugin이 제공하는 기능을 알리는 openclaw 필드가 필요합니다.

{  "name": "@myorg/openclaw-my-channel",  "version": "1.0.0",  "type": "module",  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "channel": {      "id": "my-channel",      "label": "My Channel",      "blurb": "Short description of the channel."    }  }}

{  "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"    }  }}

openclaw 필드

openclaw.channel

openclaw.channel은 런타임이 로드되기 전에 채널 검색 및 설정 화면에서 사용하는 가벼운 패키지 메타데이터입니다.

예시:

{  "openclaw": {    "channel": {      "id": "my-channel",      "label": "My Channel",      "selectionLabel": "My Channel (self-hosted)",      "detailLabel": "My Channel Bot",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "Webhook-based self-hosted chat integration.",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "Guide:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure에서 지원하는 항목은 다음과 같습니다.

• configured: 구성됨/상태 형식의 목록 화면에 채널을 포함합니다.
• setup: 대화형 설정/구성 선택기에 채널을 포함합니다.
• docs: 문서/탐색 화면에서 채널을 공개 대상으로 표시합니다.

openclaw.install

openclaw.install은 매니페스트 메타데이터가 아니라 패키지 메타데이터입니다.

{  "openclaw": {    "install": {      "npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

전체 로드 지연

채널 Plugin은 다음 설정을 사용하여 지연 로드를 활성화할 수 있습니다.

{  "openclaw": {    "extensions": ["./index.ts"],    "setupEntry": "./setup-entry.ts",    "startup": {      "deferConfiguredChannelFullLoadUntilAfterListen": true    }  }}

활성화하면 OpenClaw는 이미 구성된 채널에서도 수신 대기 전 시작 단계에 setupEntry만 로드합니다. 전체 엔트리는 Gateway가 수신 대기를 시작한 후 로드됩니다.

설정/전체 엔트리가 Gateway RPC 메서드를 등록한다면 Plugin별 접두사 아래에 두세요. 예약된 핵심 관리 네임스페이스(config.*, exec.approvals.*, wizard.*, update.*)는 핵심에서 계속 소유하며 항상 operator.admin으로 정규화됩니다.

Plugin 매니페스트

모든 네이티브 Plugin은 패키지 루트에 openclaw.plugin.json을 포함하여 배포해야 합니다. OpenClaw는 이를 사용해 Plugin 코드를 실행하지 않고 구성을 검증합니다.

{  "id": "my-plugin",  "name": "My Plugin",  "description": "Adds My Plugin capabilities to OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "Webhook verification secret"      }    }  }}

채널 Plugin의 경우 channels를 추가하고, 제공자 Plugin의 경우 providers를 추가합니다.

{  "id": "my-channel",  "channels": ["my-channel"],  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {}  }}

구성이 없는 Plugin도 스키마를 포함하여 배포해야 합니다. 빈 스키마도 유효합니다.

{  "id": "my-plugin",  "configSchema": {    "type": "object",    "additionalProperties": false  }}

전체 스키마 참조는 Plugin 매니페스트를 참조하세요.

ClawHub 게시

Skills와 Plugin 패키지는 서로 다른 ClawHub 게시 명령을 사용합니다. Plugin 패키지에는 패키지 전용 명령을 사용하세요.

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

설정 진입점

setup-entry.ts는 OpenClaw에 설정 표면(온보딩, 구성 복구, 비활성화된 채널 검사)만 필요할 때 로드하는 index.ts의 경량 대안입니다.

// setup-entry.ts  export default defineSetupPluginEntry(myChannelPlugin);

이를 통해 설정 흐름 중 무거운 런타임 코드(암호화 라이브러리, CLI 등록, 백그라운드 서비스)를 로드하지 않을 수 있습니다.

설정에 안전한 내보내기를 사이드카 모듈에 유지하는 번들 워크스페이스 채널은 defineSetupPluginEntry(...) 대신 openclaw/plugin-sdk/channel-entry-contract의 defineBundledChannelSetupEntry(...)를 사용할 수 있습니다. 이 번들 계약은 선택적 runtime 내보내기도 지원하므로 설정 시점의 런타임 연결을 경량화하고 명시적으로 유지할 수 있습니다.

범위가 좁은 설정 도우미 가져오기

설정 전용 핫 경로에서 설정 표면의 일부만 필요하다면 더 광범위한 plugin-sdk/setup 통합 진입점보다 범위가 좁은 설정 도우미 연결부를 사용하세요.

moveSingleAccountChannelSectionToDefaultAccount(...) 같은 구성 패치 도우미를 포함해 공유 설정 도구 모음 전체가 필요하다면 더 광범위한 plugin-sdk/setup 연결부를 사용하세요.

고정된 설정 마법사 문구에는 createSetupTranslator(...)를 사용하세요. 이 함수는 CLI 마법사의 로캘(OPENCLAW_LOCALE, 그다음 시스템 로캘 변수)을 따르며, 사용할 수 없으면 영어로 대체합니다. Plugin별 설정 문구는 Plugin 소유 코드에 유지하고, 공통 설정 레이블, 상태 문구 및 공식 번들 Plugin 설정 문구에만 공유 카탈로그 키를 사용하세요.

설정 패치 어댑터는 가져올 때도 핫 경로의 안전성을 유지합니다. 번들 단일 계정 승격 계약 표면 조회는 지연 실행되므로, plugin-sdk/setup-runtime을 가져와도 어댑터가 실제로 사용되기 전에는 번들 계약 표면 탐색을 즉시 로드하지 않습니다.

채널 소유 단일 계정 승격

채널이 단일 계정용 최상위 구성에서 channels.<id>.accounts.*로 업그레이드될 때, 기본 공유 동작은 승격되는 계정 범위의 값을 accounts.default로 이동합니다.

번들 채널은 설정 계약 표면을 통해 이 승격 범위를 좁히거나 동작을 재정의할 수 있습니다.

• singleAccountKeysToMove: 승격된 계정으로 이동해야 하는 추가 최상위 키
• namedAccountPromotionKeys: 명명된 계정이 이미 존재할 때 승격된 계정으로 이동할 키만 지정합니다. 공유 정책/전달 키는 채널 루트에 유지됩니다.
• resolveSingleAccountPromotionTarget(...): 승격된 값을 받을 기존 계정을 선택합니다.

구성 스키마

Plugin 구성은 매니페스트의 JSON Schema를 기준으로 검증됩니다. 사용자는 다음과 같이 Plugin을 구성합니다.

{  plugins: {    entries: {      "my-plugin": {        config: {          webhookSecret: "abc123",        },      },    },  },}

Plugin은 등록 중에 이 구성을 api.pluginConfig로 전달받습니다.

채널별 구성에는 대신 채널 구성 섹션을 사용하세요.

{  channels: {    "my-channel": {      token: "bot-token",      allowFrom: ["user1", "user2"],    },  },}

채널 구성 스키마 빌드

buildChannelConfigSchema를 사용하여 Zod 스키마를 Plugin 소유 구성 아티팩트에서 사용하는 ChannelConfigSchema 래퍼로 변환하세요.

  const accountSchema = z.object({  token: z.string().optional(),  allowFrom: z.array(z.string()).optional(),  accounts: z.object({}).catchall(z.any()).optional(),  defaultAccount: z.string().optional(),}); const configSchema = buildChannelConfigSchema(accountSchema);

계약을 이미 JSON Schema 또는 TypeBox로 작성했다면 직접 헬퍼를 사용하여 OpenClaw가 메타데이터 경로에서 Zod를 JSON Schema로 변환하는 과정을 생략할 수 있게 하세요.

  const configSchema = buildJsonChannelConfigSchema(  Type.Object({    token: Type.Optional(Type.String()),    allowFrom: Type.Optional(Type.Array(Type.String())),  }),);

서드 파티 Plugin에서도 콜드 경로 계약은 여전히 Plugin 매니페스트입니다. 생성된 JSON Schema를 openclaw.plugin.json#channelConfigs에 반영하여 구성 스키마, 설정 및 UI 표면이 런타임 코드를 로드하지 않고도 channels.<id>를 검사할 수 있게 하세요.

설정 마법사

채널 Plugin은 openclaw onboard에 대화형 설정 마법사를 제공할 수 있습니다. 마법사는 ChannelPlugin의 ChannelSetupWizard 객체입니다.

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "Connected",    unconfiguredLabel: "Not configured",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "Bot token",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "Use MY_CHANNEL_BOT_TOKEN from environment?",      keepPrompt: "Keep current token?",      inputPrompt: "Enter your bot token:",      inspect: ({ cfg, accountId }) => {        const token = (cfg.channels as any)?.["my-channel"]?.token;        return {          accountConfigured: Boolean(token),          hasConfiguredValue: Boolean(token),        };      },    },  ],};

ChannelSetupWizard는 textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize 등도 지원합니다. 전체 번들 예시는 Discord Plugin의 src/setup-core.ts를 참조하세요.

import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup"; const setupSurface = createOptionalChannelSetupSurface({  channel: "my-channel",  label: "My Channel",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// Returns { setupAdapter, setupWizard }

게시 및 설치

외부 Plugin: ClawHub에 게시한 후 설치합니다.

openclaw plugins install @myorg/openclaw-my-plugin

openclaw plugins install clawhub:@myorg/openclaw-my-plugin

openclaw plugins install npm:@myorg/openclaw-my-plugin

저장소 내 Plugin: 번들 Plugin 워크스페이스 트리 아래에 배치하세요. 빌드 중에 자동으로 검색됩니다.

번들 패키지 메타데이터는 명시적으로 정의되며, Gateway 시작 시 빌드된 JavaScript에서 추론되지 않습니다. 런타임 종속성은 이를 소유하는 Plugin 패키지에 포함되어야 하며, 패키징된 OpenClaw의 시작 과정에서는 Plugin 종속성을 복구하거나 미러링하지 않습니다.

관련 항목

• Plugin 구축 — 단계별 시작 가이드
• Plugin 매니페스트 — 전체 매니페스트 스키마 참조
• SDK 진입점 — definePluginEntry 및 defineChannelPluginEntry