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

ข้อมูลอ้างอิงสำหรับการจัดแพ็กเกจ Plugin (เมทาดาทา package.json), manifest (openclaw.plugin.json), รายการ setup และสคีมา 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 เป็นเมทาดาทาแพ็กเกจราคาถูกสำหรับการค้นพบช่องทางและพื้นผิว setup ก่อนโหลด 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
• setup: รวมช่องทางไว้ใน picker setup/configure แบบโต้ตอบ
• docs: ทำเครื่องหมายช่องทางว่าแสดงต่อสาธารณะในพื้นผิวเอกสาร/การนำทาง

openclaw.install

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

{  "openclaw": {    "install": {      "npmSpec": "@wecom/[email protected]",      "expectedIntegrity": "sha512-REPLACE_WITH_NPM_DIST_INTEGRITY",      "defaultChoice": "npm"    }  }}

การโหลดเต็มแบบเลื่อนเวลา

Plugin ช่องทางสามารถเลือกใช้การโหลดแบบเลื่อนเวลาด้วย:

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

เมื่อเปิดใช้ OpenClaw จะโหลดเฉพาะ setupEntry ระหว่างเฟส startup ก่อน listen แม้กับช่องทางที่ config แล้วก็ตาม จุดเริ่มต้นเต็มจะโหลดหลังจาก Gateway เริ่ม listen

หาก setup/full entry ของคุณลงทะเบียนเมธอด RPC ของ gateway ให้ใช้ prefix เฉพาะ Plugin namespace ผู้ดูแลระบบ core ที่สงวนไว้ (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  }}

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

การเผยแพร่ ClawHub

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

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

รายการตั้งค่า

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

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

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

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

import ตัวช่วยการตั้งค่าแบบแคบ

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

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

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

การเลื่อนระดับบัญชีเดียวที่ช่องทางเป็นเจ้าของ

เมื่อช่องทางอัปเกรดจาก config ระดับบนสุดแบบบัญชีเดียวไปเป็น channels.<id>.accounts.* behavior ที่ใช้ร่วมกันโดยค่าเริ่มต้นคือการย้ายค่าที่อยู่ในขอบเขตบัญชีที่ถูกเลื่อนระดับเข้าไปใน accounts.default

ช่องทางที่รวมมาด้วยสามารถจำกัดหรือ override การเลื่อนระดับนั้นผ่านพื้นผิว contract สำหรับการตั้งค่าของตน:

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

schema ของ config

config ของ Plugin ถูกตรวจสอบกับ JSON Schema ใน manifest ของคุณ ผู้ใช้กำหนดค่า plugins ผ่าน:

{  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 เพื่อแปลง schema ของ Zod เป็น 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 เป็น JSON Schema บน path metadata ได้:

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

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

wizard การตั้งค่า

Channel plugins สามารถให้ wizard การตั้งค่าแบบโต้ตอบสำหรับ 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),        };      },    },  ],};

type 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 }

การเผยแพร่และการติดตั้ง

Plugins ภายนอก: เผยแพร่ไปยัง 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>

เมตาดาต้าของแพ็กเกจที่รวมมาด้วยถูกระบุไว้อย่างชัดเจน ไม่ได้อนุมานจาก JavaScript ที่บิลด์แล้วเมื่อเริ่มต้น Gateway dependency ขณะรันไทม์ควรอยู่ในแพ็กเกจ Plugin ที่เป็นเจ้าของมัน การเริ่มต้น OpenClaw แบบแพ็กเกจจะไม่ซ่อมแซมหรือจำลอง dependency ของ Plugin

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

• การสร้าง Plugin — คู่มือเริ่มต้นทีละขั้นตอน
• แมนิเฟสต์ Plugin — ข้อมูลอ้างอิงสคีมาแมนิเฟสต์ฉบับเต็ม
• จุดเข้า SDK — definePluginEntry และ defineChannelPluginEntry