กลไกภายในของสถาปัตยกรรม Plugin

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

ไปป์ไลน์การโหลด

1. ค้นพบราก Plugin ที่เป็นตัวเลือก
2. อ่านแมนิเฟสต์บันเดิลแบบเนทีฟหรือเข้ากันได้ และเมทาดาตาแพ็กเกจ
3. ปฏิเสธตัวเลือกที่ไม่ปลอดภัย
4. ทำให้คอนฟิก Plugin เป็นรูปแบบมาตรฐาน (plugins.enabled, allow, deny, entries, slots, load.paths)
5. ตัดสินใจว่าจะเปิดใช้งานตัวเลือกแต่ละรายการหรือไม่
6. โหลดโมดูลเนทีฟที่เปิดใช้งาน: โมดูลบันเดิลที่สร้างแล้วใช้ตัวโหลดเนทีฟ; TypeScript ซอร์สท้องถิ่นของบุคคลที่สามใช้ Jiti fallback ฉุกเฉิน
7. เรียก hook เนทีฟ register(api) และรวบรวมการลงทะเบียนเข้าไปในรีจิสทรี Plugin
8. เปิดเผยรีจิสทรีให้กับคำสั่ง/พื้นผิวรันไทม์

​

พฤติกรรมที่ยึดแมนิเฟสต์ก่อน

• ระบุ Plugin
• ค้นพบช่องทาง/Skills/schema คอนฟิกหรือความสามารถของบันเดิลที่ประกาศไว้
• ตรวจสอบ plugins.entries.<id>.config
• เพิ่มป้ายกำกับ/placeholder ของ Control UI
• แสดงเมทาดาตาการติดตั้ง/แค็ตตาล็อก
• เก็บ descriptor การเปิดใช้งานและการตั้งค่าแบบต้นทุนต่ำไว้โดยไม่ต้องโหลดรันไทม์ Plugin

• การโหลด CLI จำกัดเหลือ Plugin ที่เป็นเจ้าของคำสั่งหลักที่ร้องขอ
• การตั้งค่าช่องทาง/การ resolve Plugin จำกัดเหลือ Plugin ที่เป็นเจ้าของ id ช่องทางที่ร้องขอ
• การตั้งค่า/การ resolve รันไทม์ของผู้ให้บริการแบบชัดเจน จำกัดเหลือ Plugin ที่เป็นเจ้าของ id ผู้ให้บริการที่ร้องขอ
• การวางแผนเริ่มต้นของ Gateway ใช้ activation.onStartup สำหรับ import ตอนเริ่มต้นและการ opt out ตอนเริ่มต้นแบบชัดเจน; Plugin ที่ไม่มีเมทาดาตาตอนเริ่มต้นจะโหลดเฉพาะ ผ่านตัวกระตุ้นการเปิดใช้งานที่แคบกว่า

​

ขอบเขตแคชของ Plugin

• PluginLoaderCacheState และรีจิสทรีรันไทม์ active ที่เข้ากันได้
• แคช jiti/module และแคชตัวโหลด public-surface ที่ใช้เพื่อหลีกเลี่ยงการ import พื้นผิวรันไทม์เดียวกันซ้ำ
• แคชระบบไฟล์สำหรับ artifact ของ Plugin ที่ติดตั้ง
• map ต่อ call อายุสั้นสำหรับการ normalize path หรือการ resolve รายการซ้ำ

• ผลการค้นพบ
• รีจิสทรีแมนิเฟสต์โดยตรง
• รีจิสทรีแมนิเฟสต์ที่สร้างใหม่จากดัชนี Plugin ที่ติดตั้ง
• การค้นหาเจ้าของผู้ให้บริการ การ suppress โมเดล นโยบายผู้ให้บริการ หรือเมทาดาตา public-artifact
• คำตอบอื่นใดที่ derive จากแมนิเฟสต์ ซึ่งแมนิเฟสต์ที่เปลี่ยน ดัชนีที่ติดตั้ง หรือ load path ควรมองเห็นได้ในการอ่านเมทาดาตาครั้งถัดไป

​

โมเดลรีจิสทรี

• record ของ Plugin (ตัวตน แหล่งที่มา origin สถานะ การวินิจฉัย)
• เครื่องมือ
• hook แบบเดิมและ hook ที่มี type
• ช่องทาง
• ผู้ให้บริการ
• handler RPC ของ Gateway
• เส้นทาง HTTP
• registrar ของ CLI
• บริการเบื้องหลัง
• คำสั่งที่ Plugin เป็นเจ้าของ

• โมดูล Plugin -> การลงทะเบียนรีจิสทรี
• รันไทม์ core -> การใช้รีจิสทรี

​

Callback การผูกการสนทนา

export default {
  id: "my-plugin",
  register(api) {
    api.onConversationBindingResolved(async (event) => {
      if (event.status === "approved") {
        // A binding now exists for this plugin + conversation.
        console.log(event.binding?.conversationId);
        return;
      }

      // The request was denied; clear any local pending state.
      console.log(event.request.conversation.conversationId);
    });
  },
};

• status: "approved" หรือ "denied"
• decision: "allow-once", "allow-always" หรือ "deny"
• binding: binding ที่ resolve แล้วสำหรับคำขอที่ได้รับอนุมัติ
• request: สรุปคำขอเดิม, detach hint, sender id และ เมทาดาตาการสนทนา

​

Hook รันไทม์ของผู้ให้บริการ

• เมทาดาตาแมนิเฟสต์ สำหรับการค้นหาก่อนรันไทม์แบบต้นทุนต่ำ: setup.providers[].envVars, ความเข้ากันได้ที่ deprecated providerAuthEnvVars, providerAuthAliases, providerAuthChoices และ channelEnvVars
• hook ช่วงคอนฟิก: catalog (discovery แบบเดิม) รวมถึง applyConfigDefaults
• hook รันไทม์: hook แบบไม่บังคับ 40+ รายการ ครอบคลุม auth, การ resolve โมเดล, การ wrap stream, ระดับ thinking, นโยบาย replay และ endpoint การใช้งาน ดู รายการเต็มใน ลำดับ hook และการใช้งาน

​

ลำดับ hook และการใช้งาน

​

ตัวอย่างผู้ให้บริการ

api.registerProvider({
  id: "example-proxy",
  label: "Example Proxy",
  auth: [],
  catalog: {
    order: "simple",
    run: async (ctx) => {
      const apiKey = ctx.resolveProviderApiKey("example-proxy").apiKey;
      if (!apiKey) {
        return null;
      }
      return {
        provider: {
          baseUrl: "https://proxy.example.com/v1",
          apiKey,
          api: "openai-completions",
          models: [{ id: "auto", name: "Auto" }],
        },
      };
    },
  },
  resolveDynamicModel: (ctx) => ({
    id: ctx.modelId,
    name: ctx.modelId,
    provider: "example-proxy",
    api: "openai-completions",
    baseUrl: "https://proxy.example.com/v1",
    reasoning: false,
    input: ["text"],
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
    contextWindow: 128000,
    maxTokens: 8192,
  }),
  prepareRuntimeAuth: async (ctx) => {
    const exchanged = await exchangeToken(ctx.apiKey);
    return {
      apiKey: exchanged.token,
      baseUrl: exchanged.baseUrl,
      expiresAt: exchanged.expiresAt,
    };
  },
  resolveUsageAuth: async (ctx) => {
    const auth = await ctx.resolveOAuthToken();
    return auth ? { token: auth.token } : null;
  },
  fetchUsageSnapshot: async (ctx) => {
    return await fetchExampleProxyUsage(ctx.token, ctx.timeoutMs, ctx.fetchFn);
  },
});

​

ตัวอย่างในตัว

​

ตัวช่วย runtime

const clip = await api.runtime.tts.textToSpeech({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const result = await api.runtime.tts.textToSpeechTelephony({
  text: "Hello from OpenClaw",
  cfg: api.config,
});

const voices = await api.runtime.tts.listVoices({
  provider: "elevenlabs",
  cfg: api.config,
});

• textToSpeech ส่งคืน payload เอาต์พุต TTS ของ core ปกติสำหรับพื้นผิว file/voice-note
• ใช้ config messages.tts ของ core และการเลือกผู้ให้บริการ
• ส่งคืน PCM audio buffer + sample rate Plugin ต้อง resample/encode สำหรับผู้ให้บริการ
• listVoices เป็น optional ต่อผู้ให้บริการ ใช้สำหรับตัวเลือกเสียงหรือ flow ตั้งค่าที่ vendor เป็นเจ้าของ
• รายการเสียงอาจมี metadata ที่ละเอียดขึ้น เช่น locale, gender และแท็ก personality สำหรับตัวเลือกที่รับรู้ผู้ให้บริการ
• OpenAI และ ElevenLabs รองรับ telephony ในปัจจุบัน Microsoft ไม่รองรับ

api.registerSpeechProvider({
  id: "acme-speech",
  label: "Acme Speech",
  isConfigured: ({ config }) => Boolean(config.messages?.tts),
  synthesize: async (req) => {
    return {
      audioBuffer: Buffer.from([]),
      outputFormat: "mp3",
      fileExtension: ".mp3",
      voiceCompatible: false,
    };
  },
});

• เก็บนโยบาย TTS, fallback และการส่ง reply ไว้ใน core
• ใช้ผู้ให้บริการ speech สำหรับพฤติกรรม synthesis ที่ vendor เป็นเจ้าของ
• อินพุต Microsoft เดิม edge ถูก normalize เป็น provider id microsoft
• โมเดลความเป็นเจ้าของที่แนะนำคือมุ่งตามบริษัท: Plugin vendor หนึ่งตัวสามารถเป็นเจ้าของ text, speech, image และผู้ให้บริการ media ในอนาคตได้เมื่อ OpenClaw เพิ่ม capability contract เหล่านั้น

api.registerMediaUnderstandingProvider({
  id: "google",
  capabilities: ["image", "audio", "video"],
  describeImage: async (req) => ({ text: "..." }),
  transcribeAudio: async (req) => ({ text: "..." }),
  describeVideo: async (req) => ({ text: "..." }),
});

• เก็บ orchestration, fallback, config และการ wiring channel ไว้ใน core
• เก็บพฤติกรรม vendor ไว้ใน Plugin ผู้ให้บริการ
• การขยายแบบ additive ควรยังมี type: เมธอด optional ใหม่, ฟิลด์ผลลัพธ์ optional ใหม่, capability optional ใหม่
• การสร้างวิดีโอใช้รูปแบบเดียวกันอยู่แล้ว:
  • core เป็นเจ้าของ capability contract และตัวช่วย runtime
  • Plugin vendor ลงทะเบียน api.registerVideoGenerationProvider(...)
  • Plugin feature/channel ใช้ api.runtime.videoGeneration.*

const image = await api.runtime.mediaUnderstanding.describeImageFile({
  filePath: "/tmp/inbound-photo.jpg",
  cfg: api.config,
  agentDir: "/tmp/agent",
});

const video = await api.runtime.mediaUnderstanding.describeVideoFile({
  filePath: "/tmp/inbound-video.mp4",
  cfg: api.config,
});

const extraction = await api.runtime.mediaUnderstanding.extractStructuredWithModel({
  provider: "codex",
  model: "gpt-5.5",
  input: [
    {
      type: "image",
      buffer: receiptImageBuffer,
      fileName: "receipt.png",
      mime: "image/png",
    },
    { type: "text", text: "Use the printed fields as the source of truth." },
  ],
  instructions: "Return entities and searchable tags.",
  schemaName: "example.evidence",
  jsonSchema: {
    type: "object",
    properties: {
      entities: { type: "array", items: { type: "string" } },
      tags: { type: "array", items: { type: "string" } },
    },
  },
  cfg: api.config,
});

const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
  filePath: "/tmp/inbound-audio.ogg",
  cfg: api.config,
  // Optional when MIME cannot be inferred reliably:
  mime: "audio/ogg",
});

• api.runtime.mediaUnderstanding.* คือพื้นผิวที่ใช้ร่วมกันที่แนะนำสำหรับ ความเข้าใจ image/audio/video
• extractStructuredWithModel(...) คือ seam ที่หันหน้าให้ Plugin สำหรับการสกัด แบบมีขอบเขตและมีผู้ให้บริการเป็นเจ้าของ โดยเน้น image เป็นหลัก ใส่อินพุต image อย่างน้อยหนึ่งรายการ; อินพุต text เป็นบริบทเสริม Plugin ผลิตภัณฑ์เป็นเจ้าของ route และ schema ของตน ส่วน OpenClaw เป็นเจ้าของ ขอบเขต provider/runtime
• ใช้ config audio ด้าน media-understanding ของ core (tools.media.audio) และลำดับ fallback ของผู้ให้บริการ
• ส่งคืน { text: undefined } เมื่อไม่มีเอาต์พุต transcription ถูกสร้างขึ้น เช่น อินพุตถูกข้าม/ไม่รองรับ
• api.runtime.stt.transcribeAudioFile(...) ยังคงเป็น alias เพื่อความเข้ากันได้

const result = await api.runtime.subagent.run({
  sessionKey: "agent:main:subagent:search-helper",
  message: "Expand this query into focused follow-up searches.",
  provider: "openai",
  model: "gpt-4.1-mini",
  deliver: false,
});

• provider และ model เป็น override ต่อ run แบบ optional ไม่ใช่การเปลี่ยน session แบบถาวร
• OpenClaw เคารพฟิลด์ override เหล่านั้นเฉพาะกับผู้เรียกที่ trusted เท่านั้น
• สำหรับ fallback run ที่ Plugin เป็นเจ้าของ operator ต้อง opt in ด้วย plugins.entries.<id>.subagent.allowModelOverride: true
• ใช้ plugins.entries.<id>.subagent.allowedModels เพื่อจำกัด Plugin ที่ trusted ให้ใช้เป้าหมาย canonical provider/model เฉพาะ หรือ "*" เพื่ออนุญาตเป้าหมายใดก็ได้อย่างชัดเจน
• subagent run ของ Plugin ที่ untrusted ยังทำงานได้ แต่คำขอ override จะถูกปฏิเสธแทนที่จะ fallback แบบเงียบ ๆ
• session subagent ที่ Plugin สร้างจะถูกแท็กด้วย plugin id ที่สร้าง Fallback api.runtime.subagent.deleteSession(...) อาจลบได้เฉพาะ session ที่เป็นเจ้าของเหล่านั้น; การลบ session ใด ๆ โดยอิสระยังต้องใช้คำขอ Gateway ที่มีขอบเขต admin

const providers = api.runtime.webSearch.listProviders({
  config: api.config,
});

const result = await api.runtime.webSearch.search({
  config: api.config,
  args: {
    query: "OpenClaw plugin runtime helpers",
    count: 5,
  },
});

• เก็บการเลือกผู้ให้บริการ, การ resolve credential และ semantics ของคำขอร่วมกันไว้ใน core
• ใช้ผู้ให้บริการ web-search สำหรับ transport การค้นหาเฉพาะ vendor
• api.runtime.webSearch.* คือพื้นผิวที่ใช้ร่วมกันที่แนะนำสำหรับ Plugin feature/channel ที่ต้องใช้พฤติกรรม search โดยไม่ขึ้นกับ wrapper เครื่องมือ agent

​

api.runtime.imageGeneration

const result = await api.runtime.imageGeneration.generate({
  config: api.config,
  args: { prompt: "A friendly lobster mascot", size: "1024x1024" },
});

const providers = api.runtime.imageGeneration.listProviders({
  config: api.config,
});

• generate(...): สร้างรูปภาพโดยใช้ chain ผู้ให้บริการ image-generation ที่กำหนดค่าไว้
• listProviders(...): แสดงรายการผู้ให้บริการ image-generation ที่พร้อมใช้งานและ capability ของพวกเขา

​

route HTTP ของ Gateway

api.registerHttpRoute({
  path: "/acme/webhook",
  auth: "plugin",
  match: "exact",
  handler: async (_req, res) => {
    res.statusCode = 200;
    res.end("ok");
    return true;
  },
});

• path: path ของ route ใต้เซิร์ฟเวอร์ HTTP ของ Gateway
• auth: ต้องระบุ ใช้ "gateway" เพื่อบังคับใช้ auth Gateway ปกติ หรือ "plugin" สำหรับ auth/การตรวจสอบ webhook ที่ Plugin จัดการ
• match: optional "exact" (ค่าเริ่มต้น) หรือ "prefix"
• replaceExisting: optional อนุญาตให้ Plugin เดียวกันแทนที่การลงทะเบียน route เดิมของตนเอง
• handler: ส่งคืน true เมื่อ route จัดการคำขอแล้ว

• api.registerHttpHandler(...) ถูกนำออกแล้วและจะทำให้เกิดข้อผิดพลาดในการโหลด Plugin ใช้ api.registerHttpRoute(...) แทน
• เส้นทางของ Plugin ต้องประกาศ auth อย่างชัดเจน
• ความขัดแย้งของ path + match ที่ตรงกันพอดีจะถูกปฏิเสธ เว้นแต่จะระบุ replaceExisting: true และ Plugin หนึ่งไม่สามารถแทนที่เส้นทางของอีก Plugin ได้
• เส้นทางที่ทับซ้อนกันและมีระดับ auth ต่างกันจะถูกปฏิเสธ ให้คงสายโซ่การส่งต่อ exact/prefix ไว้ที่ระดับ auth เดียวกันเท่านั้น
• เส้นทาง auth: "plugin" จะ ไม่ได้ รับสโคปรันไทม์ของผู้ปฏิบัติงานโดยอัตโนมัติ เส้นทางเหล่านี้มีไว้สำหรับ Webhook/การตรวจสอบลายเซ็นที่ Plugin จัดการ ไม่ใช่การเรียกตัวช่วย Gateway ที่มีสิทธิ์สูง
• เส้นทาง auth: "gateway" ทำงานภายในสโคปรันไทม์ของคำขอ Gateway แต่สโคปนั้นตั้งใจให้จำกัดอย่างระมัดระวัง:
  • การยืนยันตัวตนแบบ bearer ด้วยความลับร่วม (gateway.auth.mode = "token" / "password") จะตรึงสโคปรันไทม์ของเส้นทาง Plugin ไว้ที่ operator.write แม้ว่าผู้เรียกจะส่ง x-openclaw-scopes มาก็ตาม
  • โหมด HTTP ที่มีตัวตนที่เชื่อถือได้ (เช่น trusted-proxy หรือ gateway.auth.mode = "none" บนทางเข้าแบบส่วนตัว) จะเคารพ x-openclaw-scopes เฉพาะเมื่อมีส่วนหัวนี้อย่างชัดเจนเท่านั้น
  • หากไม่มี x-openclaw-scopes ในคำขอเส้นทาง Plugin ที่มีตัวตนเหล่านั้น สโคปรันไทม์จะย้อนกลับไปเป็น operator.write
• กฎเชิงปฏิบัติ: อย่าถือว่าเส้นทาง Plugin ที่ยืนยันตัวตนผ่าน Gateway เป็นพื้นผิวผู้ดูแลโดยนัย หากเส้นทางของคุณต้องการพฤติกรรมเฉพาะผู้ดูแล ให้กำหนดให้ใช้โหมด auth ที่มีตัวตน และจัดทำเอกสารสัญญาส่วนหัว x-openclaw-scopes อย่างชัดเจน

​

เส้นทางนำเข้า Plugin SDK

• index.js — จุดเข้า Plugin ที่บันเดิลมา
• api.js — barrel สำหรับตัวช่วย/ชนิดข้อมูล
• runtime-api.js — barrel เฉพาะรันไทม์
• setup-entry.js — จุดเข้า Plugin สำหรับการตั้งค่า

​

สคีมาของเครื่องมือข้อความ

• presentation สำหรับบล็อกการนำเสนอเชิงความหมาย (text, context, divider, buttons, select)
• delivery-pin สำหรับคำขอการส่งแบบปักหมุด

​

การ resolve เป้าหมายช่องทาง

• messaging.inferTargetChatType({ to }) ตัดสินว่าเป้าหมายที่ปรับให้อยู่ในรูปมาตรฐานแล้ว ควรถูกมองเป็น direct, group หรือ channel ก่อนค้นหาไดเรกทอรี
• messaging.targetResolver.looksLikeId(raw, normalized) บอก core ว่า อินพุตควรข้ามตรงไปยังการ resolve แบบคล้าย id แทนการค้นหาไดเรกทอรีหรือไม่
• messaging.targetResolver.resolveTarget(...) เป็น fallback ของ Plugin เมื่อ core ต้องการการ resolve ขั้นสุดท้ายที่ provider เป็นเจ้าของ หลังการทำให้เป็นมาตรฐานหรือหลัง ค้นหาไดเรกทอรีไม่พบ
• messaging.resolveOutboundSessionRoute(...) เป็นเจ้าของการสร้างเส้นทางเซสชัน เฉพาะ provider เมื่อ resolve เป้าหมายแล้ว

• ใช้ inferTargetChatType สำหรับการตัดสินใจหมวดหมู่ที่ควรเกิดก่อน การค้นหา peer/group
• ใช้ looksLikeId สำหรับการตรวจสอบ “ให้ถือค่านี้เป็น id เป้าหมายแบบชัดเจน/เนทีฟ”
• ใช้ resolveTarget สำหรับ fallback การทำให้เป็นมาตรฐานเฉพาะ provider ไม่ใช่สำหรับ การค้นหาไดเรกทอรีแบบกว้าง
• เก็บ id แบบเนทีฟของ provider เช่น chat id, thread id, JID, handle และ room id ไว้ภายในค่า target หรือพารามิเตอร์เฉพาะ provider ไม่ใช่ในฟิลด์ SDK ทั่วไป

​

ไดเรกทอรีที่มีการกำหนดค่าเป็นแหล่งข้อมูล

• peer DM ที่ขับเคลื่อนด้วย allowlist
• แผนที่ช่องทาง/กลุ่มที่กำหนดค่าไว้
• fallback ไดเรกทอรีแบบคงที่ที่จำกัดตามบัญชี

• การกรองคิวรี
• การใช้ limit
• ตัวช่วยการตัดรายการซ้ำ/การทำให้เป็นมาตรฐาน
• การสร้าง ChannelDirectoryEntry[]

​

แค็ตตาล็อก provider

• { provider } สำหรับรายการ provider หนึ่งรายการ
• { providers } สำหรับรายการ provider หลายรายการ

• simple: provider แบบ API key หรือขับเคลื่อนด้วย env ธรรมดา
• profile: provider ที่ปรากฏเมื่อมีโปรไฟล์ auth
• paired: provider ที่สังเคราะห์รายการ provider ที่เกี่ยวข้องกันหลายรายการ
• late: รอบสุดท้าย หลัง provider โดยนัยอื่น

• discovery ยังทำงานเป็น alias แบบเดิม แต่จะส่งคำเตือนการเลิกใช้งาน
• หากลงทะเบียนทั้ง catalog และ discovery OpenClaw จะใช้ catalog
• augmentModelCatalog เลิกแนะนำแล้ว provider ที่บันเดิลมาควรเผยแพร่ แถวเสริมผ่าน registerModelCatalogProvider

​

การตรวจสอบช่องทางแบบอ่านอย่างเดียว

• resolveAccount(...) คือเส้นทางรันไทม์ เส้นทางนี้ได้รับอนุญาตให้สมมติว่า credential ถูก materialize ครบถ้วนแล้ว และสามารถล้มเหลวทันทีเมื่อ secret ที่จำเป็นหายไป
• เส้นทางคำสั่งแบบอ่านอย่างเดียว เช่น openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve และ flow การซ่อมแซม doctor/config ไม่ควรต้อง materialize credential รันไทม์เพียงเพื่อ อธิบายการกำหนดค่า

• คืนเฉพาะสถานะบัญชีแบบอธิบายได้
• รักษา enabled และ configured
• รวมฟิลด์แหล่งที่มา/สถานะของ credential เมื่อเกี่ยวข้อง เช่น:
  • tokenSource, tokenStatus
  • botTokenSource, botTokenStatus
  • appTokenSource, appTokenStatus
  • signingSecretSource, signingSecretStatus
• คุณไม่จำเป็นต้องคืนค่า token ดิบเพียงเพื่อรายงานความพร้อมใช้งาน แบบอ่านอย่างเดียว การคืน tokenStatus: "available" (และฟิลด์แหล่งที่มาที่ตรงกัน) ก็เพียงพอสำหรับคำสั่งแบบสถานะ
• ใช้ configured_unavailable เมื่อ credential ถูกกำหนดค่าผ่าน SecretRef แต่ ไม่พร้อมใช้งานในเส้นทางคำสั่งปัจจุบัน

​

แพ็กแพ็กเกจ

{
  "name": "my-pack",
  "openclaw": {
    "extensions": ["./src/safety.ts", "./src/tools.ts"],
    "setupEntry": "./src/setup-entry.ts"
  }
}

• การลงทะเบียนช่องทางเอง
• HTTP routes ใดๆ ที่ต้องพร้อมใช้งานก่อน Gateway เริ่มรับฟัง
• gateway methods, tools หรือ services ใดๆ ที่ต้องมีอยู่ในช่วงเวลาเดียวกันนั้น

• singleAccountKeysToMove
• namedAccountPromotionKeys
• resolveSingleAccountPromotionTarget(...)

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

​

Metadata ของ catalog ช่องทาง

{
  "name": "@openclaw/nextcloud-talk",
  "openclaw": {
    "extensions": ["./index.ts"],
    "channel": {
      "id": "nextcloud-talk",
      "label": "Nextcloud Talk",
      "selectionLabel": "Nextcloud Talk (self-hosted)",
      "docsPath": "/channels/nextcloud-talk",
      "docsLabel": "nextcloud-talk",
      "blurb": "Self-hosted chat via Nextcloud Talk webhook bots.",
      "order": 65,
      "aliases": ["nc-talk", "nc"]
    },
    "install": {
      "npmSpec": "@openclaw/nextcloud-talk",
      "localPath": "<bundled-plugin-local-path>",
      "defaultChoice": "npm"
    }
  }
}

• detailLabel: label รองสำหรับพื้นผิว catalog/status ที่สมบูรณ์ขึ้น
• docsLabel: override ข้อความลิงก์สำหรับลิงก์เอกสาร
• preferOver: ids ของ Plugin/ช่องทางที่มีลำดับความสำคัญต่ำกว่าซึ่ง catalog entry นี้ควรมีอันดับเหนือกว่า
• selectionDocsPrefix, selectionDocsOmitLabel, selectionExtras: controls สำหรับข้อความบน selection-surface
• markdownCapable: ทำเครื่องหมายว่าช่องทางรองรับ markdown สำหรับการตัดสินใจจัดรูปแบบขาออก
• exposure.configured: ซ่อนช่องทางจากพื้นผิวรายการ configured-channel เมื่อตั้งค่าเป็น false
• exposure.setup: ซ่อนช่องทางจากตัวเลือก interactive setup/configure เมื่อตั้งค่าเป็น false
• exposure.docs: ทำเครื่องหมายช่องทางเป็น internal/private สำหรับพื้นผิวนำทางเอกสาร
• showConfigured / showInSetup: aliases แบบ legacy ที่ยังยอมรับเพื่อความเข้ากันได้; แนะนำให้ใช้ exposure
• quickstartAllowFrom: opt ช่องทางเข้าสู่ flow allowFrom ของ quickstart มาตรฐาน
• forceAccountBinding: บังคับให้ bind บัญชีอย่างชัดเจนแม้มีเพียงบัญชีเดียว
• preferSessionLookupForAnnounceTarget: แนะนำให้ใช้ session lookup เมื่อ resolve announce targets

• ~/.openclaw/mpm/plugins.json
• ~/.openclaw/mpm/catalog.json
• ~/.openclaw/plugins/catalog.json

​

Context engine plugins

import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("lossless-claw", (ctx) => ({
    info: { id: "lossless-claw", name: "Lossless Claw", ownsCompaction: true },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact() {
      return { ok: true, compacted: false };
    },
  }));
}

import {
  buildMemorySystemPromptAddition,
  delegateCompactionToRuntime,
} from "openclaw/plugin-sdk/core";

export default function (api) {
  api.registerContextEngine("my-memory-engine", (ctx) => ({
    info: {
      id: "my-memory-engine",
      name: "My Memory Engine",
      ownsCompaction: false,
    },
    async ingest() {
      return { ingested: true };
    },
    async assemble({ messages, availableTools, citationsMode }) {
      return {
        messages,
        estimatedTokens: 0,
        systemPromptAddition: buildMemorySystemPromptAddition({
          availableTools: availableTools ?? new Set(),
          citationsMode,
        }),
      };
    },
    async compact(params) {
      return await delegateCompactionToRuntime(params);
    },
  }));
}

​

การเพิ่มความสามารถใหม่

1. กำหนด core contract ตัดสินใจว่า shared behavior ใดที่ core ควรเป็นเจ้าของ: policy, fallback, config merge, lifecycle, semantics ที่ channel-facing และรูปแบบ runtime helper
2. เพิ่มพื้นผิว plugin registration/runtime ที่มี type ขยาย OpenClawPluginApi และ/หรือ api.runtime ด้วยพื้นผิวความสามารถที่ typed ขนาดเล็กที่สุดที่มีประโยชน์
3. ต่อสาย core + channel/feature consumers Channels และ feature plugins ควรใช้ความสามารถใหม่ผ่าน core ไม่ใช่โดย import vendor implementation โดยตรง
4. ลงทะเบียน vendor implementations จากนั้น vendor plugins ลงทะเบียน backends ของตนกับความสามารถนั้น
5. เพิ่ม contract coverage เพิ่ม tests เพื่อให้ ownership และ registration shape ยังชัดเจนเมื่อเวลาผ่านไป

​

Checklist ความสามารถ

• core contract types ใน src/<capability>/types.ts
• core runner/runtime helper ใน src/<capability>/runtime.ts
• พื้นผิว plugin API registration ใน src/plugins/types.ts
• การต่อสาย plugin registry ใน src/plugins/registry.ts
• การเปิดเผย plugin runtime ใน src/plugins/runtime/* เมื่อ feature/channel plugins ต้องใช้
• capture/test helpers ใน src/test-utils/plugin-registration.ts
• assertions ด้าน ownership/contract ใน src/plugins/contracts/registry.ts
• operator/plugin docs ใน docs/

​

Template ความสามารถ

// core contract
export type VideoGenerationProviderPlugin = {
  id: string;
  label: string;
  generateVideo: (req: VideoGenerationRequest) => Promise<VideoGenerationResult>;
};

// plugin API
api.registerVideoGenerationProvider({
  id: "openai",
  label: "OpenAI",
  async generateVideo(req) {
    return await generateOpenAiVideo(req);
  },
});

// shared runtime helper for feature/channel plugins
const clip = await api.runtime.videoGeneration.generate({
  prompt: "Show the robot walking through the lab.",
  cfg,
});

expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]);

• core เป็นเจ้าของ capability contract + orchestration
• vendor plugins เป็นเจ้าของ vendor implementations
• feature/channel plugins ใช้ runtime helpers
• contract tests ทำให้ ownership ชัดเจน

​

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

• สถาปัตยกรรม Plugin — โมเดลและรูปทรงความสามารถสาธารณะ
• Plugin SDK subpaths
• การตั้งค่า Plugin SDK
• การสร้าง plugins