การตั้งค่าและการกำหนดค่า Plugin

ข้อมูลอ้างอิงสำหรับการแพ็กเกจ Plugin (เมตาดาต้า package.json), manifest (openclaw.plugin.json), รายการตั้งค่า และสคีมา config.

เมตาดาต้าแพ็กเกจ

package.json ของคุณต้องมีฟิลด์ openclaw ที่บอกระบบ Plugin ว่า Plugin ของคุณมีอะไรให้ใช้:

{  "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 เป็นเมตาดาต้าแพ็กเกจที่ใช้งานเบาสำหรับการค้นพบช่องทางและพื้นผิวการตั้งค่าก่อนโหลด runtime.

ตัวอย่าง:

{  "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: รวมช่องทางในพื้นผิวรายการแบบ configured/status-style
• setup: รวมช่องทางในตัวเลือก setup/configure แบบโต้ตอบ
• docs: ทำเครื่องหมายช่องทางเป็นแบบ public-facing ในพื้นผิวเอกสาร/การนำทาง

openclaw.install

openclaw.install เป็นเมตาดาต้าแพ็กเกจ ไม่ใช่เมตาดาต้า manifest.

{  "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 ระหว่างเฟสเริ่มต้นก่อน listen แม้สำหรับช่องทางที่กำหนดค่าไว้แล้ว รายการเต็มจะโหลดหลังจาก gateway เริ่ม listen.

หาก setup/full entry ของคุณลงทะเบียน gateway RPC methods ให้เก็บไว้บน prefix เฉพาะ Plugin namespace admin หลักที่สงวนไว้ (config.*, exec.approvals.*, wizard.*, update.*) ยังคงเป็นของ core และ resolve เป็น operator.admin เสมอ.

manifest ของ Plugin

Plugin native ทุกตัวต้องจัดส่ง openclaw.plugin.json ในรากแพ็กเกจ OpenClaw ใช้สิ่งนี้เพื่อตรวจสอบ config โดยไม่รันโค้ด 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 ช่องทาง ให้เพิ่ม kind และ channels:

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

แม้ Plugin ที่ไม่มี config ก็ต้องจัดส่งสคีมา สคีมาว่างถือว่าถูกต้อง:

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

ดู Plugin manifest สำหรับข้อมูลอ้างอิง schema ฉบับเต็ม

การเผยแพร่ผ่าน ClawHub

สำหรับแพ็กเกจ Plugin ให้ใช้คำสั่ง ClawHub เฉพาะแพ็กเกจ:

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

จุดเข้า setup

ไฟล์ setup-entry.ts เป็นทางเลือกที่เบากว่า index.ts ซึ่ง OpenClaw จะโหลดเมื่อจำเป็นต้องใช้เฉพาะพื้นผิว setup เท่านั้น (onboarding, การซ่อมแซม config, การตรวจสอบช่องทางที่ปิดใช้งาน)

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

วิธีนี้หลีกเลี่ยงการโหลดโค้ด runtime ที่หนัก (ไลบรารี crypto, การลงทะเบียน CLI, บริการเบื้องหลัง) ระหว่าง flow การ setup

ช่องทาง workspace ที่ bundled ซึ่งเก็บ export ที่ปลอดภัยสำหรับ setup ไว้ในโมดูล sidecar สามารถใช้ defineBundledChannelSetupEntry(...) จาก openclaw/plugin-sdk/channel-entry-contract แทน defineSetupPluginEntry(...) ได้ contract แบบ bundled นี้ยังรองรับ export runtime แบบไม่บังคับด้วย เพื่อให้การ wiring runtime ในช่วง setup ยังคงเบาและชัดเจน

import ตัวช่วย setup แบบแคบ

สำหรับ path ที่เป็น hot setup-only ให้เลือกใช้ seam ตัวช่วย setup แบบแคบแทน umbrella plugin-sdk/setup ที่กว้างกว่า เมื่อคุณต้องใช้เพียงบางส่วนของพื้นผิว setup:

ใช้ seam plugin-sdk/setup ที่กว้างกว่าเมื่อคุณต้องการชุดเครื่องมือ setup ร่วมแบบเต็ม รวมถึงตัวช่วย config-patch เช่น moveSingleAccountChannelSectionToDefaultAccount(...)

ใช้ createSetupTranslator(...) สำหรับข้อความคงที่ของ setup wizard โดยจะทำตาม locale ของ CLI wizard (OPENCLAW_LOCALE แล้วจึงเป็นตัวแปร locale ของระบบ) และ fallback กลับเป็นภาษาอังกฤษ เก็บข้อความ setup เฉพาะ Plugin ไว้ในโค้ดที่ Plugin เป็นเจ้าของ และใช้ keys ของ catalog ที่ใช้ร่วมกันเฉพาะสำหรับ label setup ทั่วไป, ข้อความ status, และข้อความ setup ของ Plugin bundled อย่างเป็นทางการ

patch adapters สำหรับ setup ยังคงปลอดภัยต่อ hot-path เมื่อ import การ lookup contract-surface สำหรับการ promote single-account แบบ bundled เป็นแบบ lazy ดังนั้นการ import plugin-sdk/setup-runtime จะไม่โหลดการ discovery contract-surface แบบ bundled ล่วงหน้า ก่อนที่ adapter จะถูกใช้งานจริง

การ promote single-account ที่ช่องทางเป็นเจ้าของ

เมื่อช่องทางอัปเกรดจาก config ระดับบนสุดแบบ single-account ไปเป็น channels.<id>.accounts.* พฤติกรรมร่วมเริ่มต้นคือย้ายค่าที่มีขอบเขตตาม account ซึ่งถูก promote เข้าไปใน accounts.default

ช่องทาง bundled สามารถจำกัดหรือ override การ promote นั้นผ่านพื้นผิว contract ของ setup ได้:

• singleAccountKeysToMove: key ระดับบนสุดเพิ่มเติมที่ควรย้ายเข้าไปใน account ที่ถูก promote
• namedAccountPromotionKeys: เมื่อมี named accounts อยู่แล้ว เฉพาะ key เหล่านี้เท่านั้นที่จะย้ายเข้าไปใน account ที่ถูก promote; key สำหรับ shared policy/delivery จะยังอยู่ที่ root ของช่องทาง
• resolveSingleAccountPromotionTarget(...): เลือก account ที่มีอยู่ซึ่งจะรับค่าที่ถูก promote

Config schema

config ของ Plugin จะถูก validate กับ JSON Schema ใน manifest ของคุณ ผู้ใช้ config Plugin ผ่าน:

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

Plugin ของคุณจะได้รับ config นี้เป็น api.pluginConfig ระหว่างการลงทะเบียน

สำหรับ config เฉพาะช่องทาง ให้ใช้ส่วน config ของช่องทางแทน:

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

การสร้าง schema สำหรับ config ของช่องทาง

ใช้ buildChannelConfigSchema เพื่อแปลง Zod schema ให้เป็น wrapper ChannelConfigSchema ที่ใช้โดย artifact ของ config ที่ Plugin เป็นเจ้าของ:

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

ถ้าคุณเขียน contract เป็น JSON Schema หรือ TypeBox อยู่แล้ว ให้ใช้ตัวช่วยโดยตรงเพื่อให้ OpenClaw ข้ามการแปลง Zod-to-JSON-Schema บน path metadata ได้:

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

สำหรับ Plugin จากภายนอก contract บน cold-path ยังคงเป็น manifest ของ Plugin: mirror JSON Schema ที่สร้างแล้วเข้าไปใน openclaw.plugin.json#channelConfigs เพื่อให้ config schema, setup, และพื้นผิว UI สามารถตรวจสอบ channels.<id> ได้โดยไม่ต้องโหลดโค้ด runtime

Setup wizards

Plugin ช่องทางสามารถจัดเตรียม setup wizards แบบโต้ตอบสำหรับ openclaw onboard ได้ wizard คือออบเจ็กต์ ChannelSetupWizard บน ChannelPlugin:

 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 แบบ bundled (เช่น Plugin Discord 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 ใน repo: วางไว้ใต้ทรี workspace ของ Plugin ที่ bundled แล้วระบบจะค้นพบโดยอัตโนมัติระหว่างการ build

ผู้ใช้สามารถติดตั้งได้:

openclaw plugins install <package-name>

metadata ของแพ็กเกจ bundled เป็นแบบระบุชัดเจน ไม่ได้อนุมานจาก JavaScript ที่ build แล้วตอนเริ่มต้น gateway dependency ขณะ runtime ควรอยู่ในแพ็กเกจ Plugin ที่เป็นเจ้าของ dependency เหล่านั้น; การเริ่มต้น OpenClaw แบบแพ็กเกจจะไม่ซ่อมแซมหรือ mirror dependency ของ Plugin

ที่เกี่ยวข้อง

• การสร้าง Plugin — คู่มือเริ่มต้นทีละขั้นตอน
• manifest ของ Plugin — เอกสารอ้างอิง schema ของ manifest ฉบับเต็ม
• entry point ของ SDK — definePluginEntry และ defineChannelPluginEntry