Plugin 설정 및 구성

Plugin 패키징(package.json 메타데이터), 매니페스트(openclaw.plugin.json), 설정 항목, config 스키마에 대한 레퍼런스입니다.

패키지 메타데이터

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",  "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는 이미 구성된 채널의 경우에도 사전 listen 시작 단계에서 setupEntry만 로드합니다. 전체 진입점은 gateway가 listen을 시작한 뒤 로드됩니다.

설정/전체 진입점이 gateway RPC 메서드를 등록하는 경우 Plugin별 접두사에 유지하세요. 예약된 핵심 관리자 네임스페이스(config.*, exec.approvals.*, wizard.*, update.*)는 핵심 소유로 유지되며 항상 operator.admin으로 해석됩니다.

Plugin 매니페스트

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

{  "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의 경우 kind와 channels를 추가합니다.

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

config가 없는 Plugin도 스키마를 포함해야 합니다. 빈 스키마도 유효합니다.

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

Plugin 매니페스트에서 전체 스키마 참조를 확인하세요.

ClawHub 게시

Plugin 패키지에는 패키지별 ClawHub 명령을 사용하세요:

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"],    },  },}

채널 구성 스키마 빌드

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

  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-to-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 타입은 credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize 등을 지원합니다. 전체 예시는 번들 Plugin 패키지(예: Discord Plugin src/channel.setup.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 워크스페이스 트리 아래에 배치하면 빌드 중 자동으로 발견됩니다.

사용자는 다음과 같이 설치할 수 있습니다.

openclaw plugins install <package-name>

번들 패키지 메타데이터는 Gateway 시작 시 빌드된 JavaScript에서 추론되지 않고 명시됩니다. 런타임 의존성은 해당 의존성을 소유한 Plugin 패키지에 속합니다. 패키징된 OpenClaw 시작 과정은 Plugin 의존성을 복구하거나 미러링하지 않습니다.

관련 항목

• Plugin 빌드 — 단계별 시작 가이드
• Plugin manifest — 전체 manifest 스키마 참조
• SDK 진입점 — definePluginEntry 및 defineChannelPluginEntry