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

ข้อมูลอ้างอิงสำหรับการจัดแพ็กเกจ Plugin (ข้อมูลเมตา package.json), ไฟล์ manifest (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": "ช่องทางของฉัน",      "blurb": "คำอธิบายสั้นๆ ของช่องทาง"    }  }}

{  "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": "ช่องทางของฉัน",      "selectionLabel": "ช่องทางของฉัน (โฮสต์เอง)",      "detailLabel": "บอตช่องทางของฉัน",      "docsPath": "/channels/my-channel",      "docsLabel": "my-channel",      "blurb": "การเชื่อมต่อแชตแบบโฮสต์เองที่ใช้ Webhook",      "order": 80,      "aliases": ["mc"],      "preferOver": ["my-channel-legacy"],      "selectionDocsPrefix": "คู่มือ:",      "selectionExtras": ["Markdown"],      "markdownCapable": true,      "exposure": {        "configured": true,        "setup": true,        "docs": true      },      "quickstartAllowFrom": true    }  }}

exposure รองรับ:

• configured: รวมช่องทางไว้ในหน้ารายการแบบการกำหนดค่า/สถานะ
• setup: รวมช่องทางไว้ในตัวเลือกการตั้งค่า/กำหนดค่าแบบโต้ตอบ
• docs: ระบุว่าช่องทางเปิดเผยต่อสาธารณะในหน้าเอกสาร/การนำทาง

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 ระหว่างช่วงเริ่มต้นก่อนเริ่มรับฟัง แม้เป็นช่องทางที่กำหนดค่าไว้แล้วก็ตาม จุดเริ่มต้นแบบเต็มจะโหลดหลังจาก Gateway เริ่มรับฟัง

หาก entry สำหรับการตั้งค่า/แบบเต็มของคุณลงทะเบียนเมธอด RPC ของ Gateway ให้ใช้คำนำหน้าเฉพาะ Plugin สงวนเนมสเปซผู้ดูแลระบบหลัก (config.*, exec.approvals.*, wizard.*, update.*) ไว้ให้แกนหลักเป็นเจ้าของ และทำให้เป็นมาตรฐานเป็น operator.admin เสมอ

Manifest ของ Plugin

Plugin แบบเนทีฟทุกตัวต้องจัดส่ง openclaw.plugin.json ที่รากของแพ็กเกจ OpenClaw ใช้ไฟล์นี้เพื่อตรวจสอบความถูกต้องของการกำหนดค่าโดยไม่เรียกใช้โค้ดของ Plugin

{  "id": "my-plugin",  "name": "Plugin ของฉัน",  "description": "เพิ่มความสามารถของ Plugin ของฉันให้กับ OpenClaw",  "configSchema": {    "type": "object",    "additionalProperties": false,    "properties": {      "webhookSecret": {        "type": "string",        "description": "ข้อมูลลับสำหรับตรวจสอบ Webhook"      }    }  }}

สำหรับ 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  }}

ดูข้อมูลอ้างอิงสคีมาฉบับเต็มได้ที่ Manifest ของ Plugin

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

แพ็กเกจ Skills และ Plugin ใช้คำสั่งเผยแพร่ของ ClawHub แยกกัน สำหรับแพ็กเกจ Plugin ให้ใช้คำสั่งเฉพาะแพ็กเกจ:

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

Entry สำหรับการตั้งค่า

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

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

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

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

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

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

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

ใช้ createSetupTranslator(...) สำหรับข้อความคงที่ของวิซาร์ดการตั้งค่า โดยจะใช้ค่าที่ไม่ว่างค่าแรกจาก OPENCLAW_LOCALE, LC_ALL, LC_MESSAGES และ LANG ตามลำดับ แล้วจึงใช้ภาษาอังกฤษเป็นค่าเริ่มต้น ตั้งค่า OPENCLAW_LOCALE=en เพื่อแทนที่ด้วยภาษาอังกฤษอย่างชัดเจน เก็บข้อความการตั้งค่าเฉพาะ Plugin ไว้ในโค้ดที่ Plugin เป็นเจ้าของ และใช้คีย์แค็ตตาล็อกที่ใช้ร่วมกันเฉพาะสำหรับป้ายกำกับการตั้งค่าทั่วไป, ข้อความสถานะ และข้อความการตั้งค่าของ Plugin ทางการที่รวมมาให้

อะแดปเตอร์แพตช์การตั้งค่ายังคงปลอดภัยสำหรับเส้นทางด่วนเมื่อนำเข้า การค้นหาพื้นผิวสัญญาสำหรับการเลื่อนระดับบัญชีเดียวที่รวมมาให้จะทำงานแบบ lazy ดังนั้นการนำเข้า plugin-sdk/setup-runtime จะไม่โหลดการค้นหาพื้นผิวสัญญาที่รวมมาให้ล่วงหน้าก่อนใช้งานอะแดปเตอร์จริง

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

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

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

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

สคีมาการกำหนดค่า

การกำหนดค่าของ Plugin จะได้รับการตรวจสอบกับ JSON Schema ใน Manifest ผู้ใช้กำหนดค่า Plugin ผ่าน:

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

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

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

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

การสร้างสคีมาการกำหนดค่าช่องทาง

ใช้ buildChannelConfigSchema เพื่อแปลงสคีมา Zod เป็น wrapper 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 ของบุคคลที่สาม สัญญาของเส้นทางเย็นยังคงเป็น Manifest ของ Plugin: ทำสำเนา JSON Schema ที่สร้างขึ้นไว้ใน openclaw.plugin.json#channelConfigs เพื่อให้พื้นผิวสคีมาการกำหนดค่า, การตั้งค่า และ UI สามารถตรวจสอบ channels.<id> ได้โดยไม่โหลดโค้ดรันไทม์

วิซาร์ดการตั้งค่า

Plugin ช่องทางสามารถมีวิซาร์ดการตั้งค่าแบบโต้ตอบสำหรับ openclaw onboard ได้ วิซาร์ดเป็นออบเจ็กต์ ChannelSetupWizard บน ChannelPlugin:

 const setupWizard: ChannelSetupWizard = {  channel: "my-channel",  status: {    configuredLabel: "เชื่อมต่อแล้ว",    unconfiguredLabel: "ยังไม่ได้กำหนดค่า",    resolveConfigured: ({ cfg }) => Boolean((cfg.channels as any)?.["my-channel"]?.token),  },  credentials: [    {      inputKey: "token",      providerHint: "my-channel",      credentialLabel: "โทเค็นของบอต",      preferredEnvVar: "MY_CHANNEL_BOT_TOKEN",      envPrompt: "ใช้ MY_CHANNEL_BOT_TOKEN จากสภาพแวดล้อมหรือไม่",      keepPrompt: "เก็บโทเค็นปัจจุบันไว้หรือไม่",      inputPrompt: "ป้อนโทเค็นของบอต:",      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: "ช่องทางของฉัน",  npmSpec: "@myorg/openclaw-my-channel",  docsPath: "/channels/my-channel",});// คืนค่า { 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