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

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

เมทาดาทาแพ็กเกจ

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",  "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 เริ่มรับฟัง

หากจุดเริ่มต้นการตั้งค่า/แบบเต็มของคุณลงทะเบียนเมธอด RPC ของ Gateway ให้ใช้คำนำหน้าที่เฉพาะเจาะจงกับ 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 เป็นทางเลือกที่มีน้ำหนักเบาแทน index.ts ซึ่ง OpenClaw จะโหลดเมื่อต้องการเฉพาะส่วนติดต่อสำหรับการตั้งค่า (การเริ่มต้นใช้งาน การซ่อมแซมการกำหนดค่า การตรวจสอบช่องทางที่ปิดใช้งาน):

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

วิธีนี้ช่วยหลีกเลี่ยงการโหลดโค้ดรันไทม์ขนาดใหญ่ (ไลบรารีการเข้ารหัส การลงทะเบียน CLI บริการเบื้องหลัง) ระหว่างขั้นตอนการตั้งค่า

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

การนำเข้าตัวช่วยการตั้งค่าแบบเฉพาะเจาะจง

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

ใช้ส่วนเชื่อมต่อ plugin-sdk/setup ที่กว้างกว่าเมื่อต้องการชุดเครื่องมือการตั้งค่าที่ใช้ร่วมกันทั้งหมด รวมถึงตัวช่วยแก้ไขการกำหนดค่า เช่น moveSingleAccountChannelSectionToDefaultAccount(...)

ใช้ 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 เป็นตัวห่อหุ้ม ChannelConfigSchema ที่อาร์ติแฟกต์การกำหนดค่าซึ่ง 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);

หากคุณเขียนสัญญาเป็น 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 ได้ ตัวช่วยสร้างคืออ็อบเจกต์ 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 ยังรองรับ textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize และอื่น ๆ ดูตัวอย่างองค์ประกอบที่รวมมาฉบับเต็มได้จาก src/setup-core.ts ของ Plugin Discord

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 ที่รวมมาให้ ระบบจะค้นพบโดยอัตโนมัติระหว่างการบิลด์

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

เนื้อหาที่เกี่ยวข้อง

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