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

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

# manifest ของ Plugin

Plugin native ทุกตัวต้องมี 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 ช่องทาง ให้เพิ่ม kind และ channels:

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

แม้แต่ Plugin ที่ไม่มีคอนฟิกก็ต้องมีสคีมา สคีมาว่างถือว่า valid:

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

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

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

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

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

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

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

// setup-entry.ts


export default defineSetupPluginEntry(myChannelPlugin);

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

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

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

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

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

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

# การโปรโมตบัญชีเดียวที่ช่องทางเป็นเจ้าของ

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

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

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

# schema ของ config

config ของ Plugin จะถูกตรวจสอบกับ JSON Schema ใน manifest ของคุณ ผู้ใช้กำหนดค่า 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 เพื่อแปลง 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);

หากคุณเขียนสัญญาเป็น 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())),
  }),
);

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

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

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 รองรับ credentials, textInputs, dmPolicy, allowFrom, groupAccess, prepare, finalize และอื่น ๆ ดูตัวอย่างเต็มในแพ็กเกจ Plugin ที่รวมมาด้วย (เช่น 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 ในรีโป: วางไว้ใต้แผนผังเวิร์กสเปซ Plugin ที่รวมมา และระบบจะค้นพบโดยอัตโนมัติระหว่างการ build

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

openclaw plugins install <package-name>

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

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

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