Plugins

ฮุกของ Plugin

Hook ของ Plugin เป็นจุดขยายแบบ in-process สำหรับ Plugin ของ OpenClaw ใช้เมื่อ Plugin ต้องตรวจสอบหรือเปลี่ยนการรันของเอเจนต์ การเรียกเครื่องมือ ลำดับข้อความ วงจรชีวิตเซสชัน การกำหนดเส้นทางซับเอเจนต์ การติดตั้ง หรือการเริ่มต้น Gateway

ใช้ Hook ภายใน แทนเมื่อคุณต้องการสคริปต์ HOOK.md ขนาดเล็กที่ติดตั้งโดยผู้ปฏิบัติการ สำหรับเหตุการณ์คำสั่งและ Gateway เช่น /new, /reset, /stop, agent:bootstrap หรือ gateway:startup

เริ่มต้นอย่างรวดเร็ว

ลงทะเบียน Hook ของ Plugin แบบมีชนิดด้วย api.on(...) จากจุดเข้าของ Plugin:


export default definePluginEntry({
  id: "tool-preflight",
  name: "Tool Preflight",
  register(api) {
    api.on(
      "before_tool_call",
      async (event) => {
        if (event.toolName !== "web_search") {
          return;
        }

        return {
          requireApproval: {
            title: "Run web search",
            description: `Allow search query: ${String(event.params.query ?? "")}`,
            severity: "info",
            timeoutMs: 60_000,
            timeoutBehavior: "deny",
          },
        };
      },
      { priority: 50 },
    );
  },
});

ตัวจัดการ Hook จะทำงานตามลำดับจาก priority สูงไปต่ำ Hook ที่มีลำดับความสำคัญเท่ากัน จะรักษาลำดับการลงทะเบียนไว้

api.on(name, handler, opts?) รับค่า:

priority - ลำดับการทำงานของตัวจัดการ (ค่าสูงกว่าจะทำงานก่อน)
timeoutMs - งบเวลาต่อ Hook แบบไม่บังคับ เมื่อกำหนดไว้ ตัวรัน Hook จะยกเลิก ตัวจัดการนั้นหลังงบเวลาหมดลงและทำงานตัวถัดไป แทนที่จะปล่อยให้งานตั้งค่าหรือเรียกคืนที่ช้า ใช้เวลาของ timeout โมเดลที่ผู้เรียกกำหนดไว้ ข้ามค่านี้เพื่อใช้ timeout การสังเกต/การตัดสินใจเริ่มต้นที่ตัวรัน Hook นำไปใช้แบบทั่วไป

ผู้ปฏิบัติการสามารถตั้งงบเวลา Hook ได้โดยไม่ต้องแพตช์โค้ด Plugin ด้วย:

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "timeoutMs": 30000,
          "timeouts": {
            "before_prompt_build": 90000,
            "agent_end": 60000
          }
        }
      }
    }
  }
}

hooks.timeouts.<hookName> จะแทนที่ hooks.timeoutMs ซึ่งจะแทนที่ค่า api.on(..., { timeoutMs }) ที่ผู้เขียน Plugin กำหนดไว้ ค่าที่กำหนดแต่ละค่าต้องเป็น จำนวนเต็มบวกไม่เกิน 600000 มิลลิวินาที ควรใช้การแทนที่ราย Hook สำหรับ Hook ที่ทราบว่าช้า เพื่อไม่ให้ Plugin หนึ่งได้รับงบเวลาที่ยาวขึ้นในทุกจุด

แต่ละ Hook จะได้รับ event.context.pluginConfig ซึ่งเป็นค่ากำหนดที่แก้ไขแล้วสำหรับ Plugin ที่ลงทะเบียนตัวจัดการนั้น ใช้ค่านี้สำหรับการตัดสินใจของ Hook ที่ต้องใช้ ตัวเลือกปัจจุบันของ Plugin; OpenClaw จะแทรกค่านี้ให้ต่อหนึ่งตัวจัดการโดยไม่เปลี่ยนแปลง อ็อบเจ็กต์เหตุการณ์ร่วมที่ Plugin อื่นเห็น

แค็ตตาล็อก Hook

Hook ถูกจัดกลุ่มตามพื้นผิวที่ขยาย ชื่อที่เป็น ตัวหนา รับผลลัพธ์การตัดสินใจ (บล็อก ยกเลิก แทนที่ หรือขออนุมัติ); รายการอื่นทั้งหมดเป็นแบบสังเกตการณ์เท่านั้น

เทิร์นของเอเจนต์

before_model_resolve - แทนที่ผู้ให้บริการหรือโมเดลก่อนโหลดข้อความเซสชัน
agent_turn_prepare - ใช้การแทรกเทิร์นของ Plugin ที่เข้าคิวไว้และเพิ่มบริบทในเทิร์นเดียวกันก่อน Hook พร้อมท์
before_prompt_build - เพิ่มบริบทแบบไดนามิกหรือข้อความพร้อมท์ระบบก่อนการเรียกโมเดล
before_agent_start - เฟสรวมเพื่อความเข้ากันได้เท่านั้น; ควรใช้ Hook สองรายการข้างต้น
before_agent_run - ตรวจสอบพร้อมท์สุดท้ายและข้อความเซสชันก่อนส่งเข้าโมเดล และเลือกบล็อกการรันได้
before_agent_reply - ลัดวงจรเทิร์นของโมเดลด้วยคำตอบสังเคราะห์หรือความเงียบ
before_agent_finalize - ตรวจสอบคำตอบสุดท้ายตามธรรมชาติและขอให้โมเดลทำงานอีกหนึ่งรอบ
agent_end - สังเกตข้อความสุดท้าย สถานะสำเร็จ และระยะเวลาการรัน
heartbeat_prompt_contribution - เพิ่มบริบทเฉพาะ Heartbeat สำหรับ Plugin ตรวจสอบเบื้องหลังและวงจรชีวิต

การสังเกตบทสนทนา

model_call_started / model_call_ended - สังเกตเมทาดาทาการเรียกผู้ให้บริการ/โมเดลที่ทำให้ปลอดภัยแล้ว เวลา ผลลัพธ์ และแฮชรหัสคำขอแบบจำกัด โดยไม่มีเนื้อหาพร้อมท์หรือคำตอบ
llm_input - สังเกตอินพุตของผู้ให้บริการ (พร้อมท์ระบบ พร้อมท์ ประวัติ)
llm_output - สังเกตเอาต์พุตของผู้ให้บริการ

เครื่องมือ

before_tool_call - เขียนพารามิเตอร์เครื่องมือใหม่ บล็อกการดำเนินการ หรือขออนุมัติ
after_tool_call - สังเกตผลลัพธ์เครื่องมือ ข้อผิดพลาด และระยะเวลา
tool_result_persist - เขียนข้อความผู้ช่วยที่สร้างจากผลลัพธ์เครื่องมือใหม่
before_message_write - ตรวจสอบหรือบล็อกการเขียนข้อความที่กำลังดำเนินอยู่ (พบไม่บ่อย)

ข้อความและการส่งมอบ

inbound_claim - อ้างสิทธิ์ข้อความขาเข้าก่อนการกำหนดเส้นทางเอเจนต์ (คำตอบสังเคราะห์)
message_received - สังเกตเนื้อหาขาเข้า ผู้ส่ง เธรด และเมทาดาทา
message_sending - เขียนเนื้อหาขาออกใหม่หรือยกเลิกการส่งมอบ
message_sent - สังเกตความสำเร็จหรือความล้มเหลวของการส่งมอบขาออก
before_dispatch - ตรวจสอบหรือเขียน dispatch ขาออกใหม่ก่อนส่งต่อให้ช่องทาง
reply_dispatch - มีส่วนร่วมใน pipeline การ dispatch คำตอบสุดท้าย

เซสชันและ Compaction

session_start / session_end - ติดตามขอบเขตวงจรชีวิตเซสชัน
before_compaction / after_compaction - สังเกตหรือใส่คำอธิบายประกอบรอบ Compaction
before_reset - สังเกตเหตุการณ์รีเซ็ตเซสชัน (/reset, การรีเซ็ตแบบโปรแกรม)

ซับเอเจนต์

subagent_spawning / subagent_delivery_target / subagent_spawned / subagent_ended - ประสานการกำหนดเส้นทางซับเอเจนต์และการส่งมอบเมื่อเสร็จสิ้น

วงจรชีวิต

gateway_start / gateway_stop - เริ่มหรือหยุดบริการที่ Plugin เป็นเจ้าของพร้อมกับ Gateway
cron_changed - สังเกตการเปลี่ยนแปลงวงจรชีวิต Cron ที่ Gateway เป็นเจ้าของ (เพิ่ม อัปเดต ลบ เริ่มต้น เสร็จสิ้น จัดกำหนดการ)
before_install - ตรวจสอบการสแกนติดตั้ง Skills หรือ Plugin และเลือกบล็อกได้

นโยบายการเรียกเครื่องมือ

before_tool_call ได้รับ:

event.toolName
event.params
event.runId แบบไม่บังคับ
event.toolCallId แบบไม่บังคับ
ฟิลด์บริบท เช่น ctx.agentId, ctx.sessionKey, ctx.sessionId, ctx.runId, ctx.jobId (ตั้งค่าในการรันที่ขับเคลื่อนด้วย Cron) และ ctx.trace สำหรับวินิจฉัย

สามารถคืนค่า:

type BeforeToolCallResult = {
  params?: Record<string, unknown>;
  block?: boolean;
  blockReason?: string;
  requireApproval?: {
    title: string;
    description: string;
    severity?: "info" | "warning" | "critical";
    timeoutMs?: number;
    timeoutBehavior?: "allow" | "deny";
    pluginId?: string;
    onResolution?: (
      decision: "allow-once" | "allow-always" | "deny" | "timeout" | "cancelled",
    ) => Promise<void> | void;
  };
};

กฎ:

block: true เป็นจุดสิ้นสุดและข้ามตัวจัดการที่มีลำดับความสำคัญต่ำกว่า
block: false จะถือว่าไม่มีการตัดสินใจ
params เขียนพารามิเตอร์เครื่องมือใหม่สำหรับการดำเนินการ
requireApproval หยุดการรันเอเจนต์ชั่วคราวและถามผู้ใช้ผ่านการอนุมัติของ Plugin คำสั่ง /approve สามารถอนุมัติได้ทั้งการอนุมัติ exec และการอนุมัติ Plugin
block: true ที่มีลำดับความสำคัญต่ำกว่ายังสามารถบล็อกได้หลังจาก Hook ที่มีลำดับความสำคัญสูงกว่า ขออนุมัติแล้ว
onResolution ได้รับการตัดสินใจอนุมัติที่แก้ไขแล้ว - allow-once, allow-always, deny, timeout หรือ cancelled

Plugin ที่รวมมากับระบบซึ่งต้องใช้นโยบายระดับโฮสต์สามารถลงทะเบียนนโยบายเครื่องมือที่เชื่อถือได้ ด้วย api.registerTrustedToolPolicy(...) นโยบายเหล่านี้จะทำงานก่อน Hook before_tool_call ปกติ และก่อนการตัดสินใจของ Plugin ภายนอก ใช้เฉพาะสำหรับ ด่านตรวจที่โฮสต์ไว้วางใจ เช่น นโยบายพื้นที่ทำงาน การบังคับใช้งบประมาณ หรือ ความปลอดภัยของเวิร์กโฟลว์ที่สงวนไว้ Plugin ภายนอกควรใช้ Hook before_tool_call ปกติ

การคงอยู่ของผลลัพธ์เครื่องมือ

ผลลัพธ์เครื่องมือสามารถมี details แบบมีโครงสร้างสำหรับการเรนเดอร์ UI การวินิจฉัย การกำหนดเส้นทางสื่อ หรือเมทาดาทาที่ Plugin เป็นเจ้าของ ให้ถือว่า details เป็นเมทาดาทารันไทม์ ไม่ใช่เนื้อหาพร้อมท์:

OpenClaw ลบ toolResult.details ก่อนการเล่นซ้ำให้ผู้ให้บริการและอินพุต Compaction เพื่อไม่ให้เมทาดาทากลายเป็นบริบทของโมเดล
รายการเซสชันที่คงอยู่จะเก็บเฉพาะ details แบบจำกัด รายละเอียดที่ใหญ่เกินไปจะ ถูกแทนที่ด้วยสรุปขนาดกะทัดรัดและ persistedDetailsTruncated: true
tool_result_persist และ before_message_write ทำงานก่อนเพดานการคงอยู่สุดท้าย Hook ยังคงควรรักษา details ที่คืนค่าให้เล็ก และหลีกเลี่ยงการวางข้อความที่เกี่ยวข้องกับพร้อมท์ ไว้เฉพาะใน details; ให้วางเอาต์พุตเครื่องมือที่โมเดลมองเห็นได้ใน content

Hook ของพร้อมท์และโมเดล

ใช้ Hook เฉพาะเฟสสำหรับ Plugin ใหม่:

before_model_resolve: ได้รับเฉพาะพร้อมท์ปัจจุบันและเมทาดาทาไฟล์แนบ คืนค่า providerOverride หรือ modelOverride
agent_turn_prepare: ได้รับพร้อมท์ปัจจุบัน ข้อความเซสชันที่เตรียมไว้ และการแทรกที่เข้าคิวไว้แบบครั้งเดียวพอดีซึ่งถูกระบายออกสำหรับเซสชันนี้ คืนค่า prependContext หรือ appendContext
before_prompt_build: ได้รับพร้อมท์ปัจจุบันและข้อความเซสชัน คืนค่า prependContext, appendContext, systemPrompt, prependSystemContext หรือ appendSystemContext
heartbeat_prompt_contribution: ทำงานเฉพาะสำหรับเทิร์น Heartbeat และคืนค่า prependContext หรือ appendContext มีไว้สำหรับตัวตรวจสอบเบื้องหลัง ที่ต้องสรุปสถานะปัจจุบันโดยไม่เปลี่ยนเทิร์นที่ผู้ใช้เริ่มต้น

before_agent_start ยังคงอยู่เพื่อความเข้ากันได้ ควรใช้ Hook แบบชัดเจนข้างต้น เพื่อให้ Plugin ของคุณไม่ขึ้นกับเฟสรวมแบบเดิม

before_agent_run ทำงานหลังการสร้างพร้อมท์และก่อนอินพุตโมเดลใดๆ รวมถึงการโหลดรูปภาพเฉพาะพร้อมท์และการสังเกต llm_input ได้รับ อินพุตผู้ใช้ปัจจุบันเป็น prompt พร้อมกับประวัติเซสชันที่โหลดแล้วใน messages และพร้อมท์ระบบที่ใช้งานอยู่ คืนค่า { outcome: "block", reason, message? } เพื่อหยุดการรันก่อนที่โมเดลจะอ่านข้อความพร้อมท์ได้ reason เป็นข้อมูลภายใน; message เป็นข้อความแทนที่ที่แสดงต่อผู้ใช้ ผลลัพธ์ที่รองรับมีเพียง pass และ block; รูปแบบการตัดสินใจที่ไม่รองรับจะปิดแบบปลอดภัย

เมื่อการรันถูกบล็อก OpenClaw จะเก็บเฉพาะข้อความแทนที่ใน message.content พร้อมเมทาดาทาการบล็อกที่ไม่อ่อนไหว เช่น id ของ Plugin ที่บล็อก และประทับเวลา ข้อความผู้ใช้ต้นฉบับจะไม่ถูกเก็บไว้ในทรานสคริปต์หรือบริบทในอนาคต เหตุผลการบล็อกภายในถือเป็นข้อมูลอ่อนไหวและถูกแยกออกจาก ทรานสคริปต์ ประวัติ broadcast log และ payload การวินิจฉัย ความสามารถในการสังเกต ควรใช้ฟิลด์ที่ทำให้ปลอดภัยแล้ว เช่น id ของผู้บล็อก ผลลัพธ์ ประทับเวลา หรือหมวดหมู่ที่ปลอดภัย

before_agent_start และ agent_end มี event.runId เมื่อ OpenClaw สามารถ ระบุการรันที่ใช้งานอยู่ได้ ค่าเดียวกันยังอยู่ใน ctx.runId ด้วย การรันที่ขับเคลื่อนด้วย Cron ยังเปิดเผย ctx.jobId (id ของงาน Cron ต้นทาง) เพื่อให้ Hook ของ Plugin สามารถจำกัดขอบเขตเมตริก ผลข้างเคียง หรือสถานะไว้กับงานที่จัดกำหนดการเฉพาะได้

สำหรับการรันที่มาจากช่องทาง ctx.messageProvider คือพื้นผิวผู้ให้บริการ เช่น discord หรือ telegram ส่วน ctx.channelId คือรหัสเป้าหมายบทสนทนา เมื่อ OpenClaw สามารถอนุมานได้จากคีย์เซสชันหรือเมทาดาทาการส่งมอบ

agent_end เป็น Hook สำหรับสังเกตการณ์และทำงานแบบ fire-and-forget หลังเทิร์น ตัวรัน Hook ใช้ timeout 30 วินาที เพื่อไม่ให้ Plugin หรือ endpoint embedding ที่ค้างอยู่ปล่อยให้ promise ของ Hook ค้างตลอดไป timeout จะถูกบันทึกใน log และ OpenClaw จะดำเนินต่อ; จะไม่ยกเลิกงานเครือข่ายที่ Plugin เป็นเจ้าของ เว้นแต่ Plugin จะใช้สัญญาณยกเลิกของตนเองด้วย

ใช้ model_call_started และ model_call_ended สำหรับเทเลเมทรีการเรียกผู้ให้บริการ ที่ไม่ควรได้รับพร้อมท์ดิบ ประวัติ คำตอบ ส่วนหัว เนื้อหาคำขอ หรือรหัสคำขอของผู้ให้บริการ Hook เหล่านี้มีเมทาดาทาที่เสถียร เช่น runId, callId, provider, model, api/transport แบบไม่บังคับ, durationMs/outcome สุดท้าย และ upstreamRequestIdHash เมื่อ OpenClaw สามารถอนุมาน แฮชรหัสคำขอของผู้ให้บริการแบบจำกัดได้

before_agent_finalize ทำงานเฉพาะเมื่อ harness กำลังจะยอมรับ คำตอบผู้ช่วยสุดท้ายตามธรรมชาติ ไม่ใช่เส้นทางการยกเลิก /stop และจะไม่ ทำงานเมื่อผู้ใช้ยกเลิกเทิร์น คืนค่า { action: "revise", reason } เพื่อขอให้ harness ทำโมเดลอีกหนึ่งรอบก่อนสรุปผล, { action: "finalize", reason? } เพื่อบังคับสรุปผล หรือไม่คืนผลลัพธ์เพื่อดำเนินต่อ Hook Stop แบบเนทีฟของ Codex จะถูกส่งต่อเข้า Hook นี้เป็นการตัดสินใจ before_agent_finalize ของ OpenClaw

เมื่อคืนค่า action: "revise" Plugin สามารถใส่เมทาดาทา retry เพื่อทำให้ รอบโมเดลเพิ่มเติมมีขอบเขตและเล่นซ้ำได้อย่างปลอดภัย:

type BeforeAgentFinalizeRetry = {
  instruction: string;
  idempotencyKey?: string;
  maxAttempts?: number;
};

instruction จะถูกต่อท้ายกับเหตุผลการแก้ไขที่ส่งไปยังฮาร์เนส idempotencyKey ช่วยให้โฮสต์นับการลองซ้ำสำหรับคำขอ Plugin เดียวกันข้ามการตัดสินใจ finalize ที่เทียบเท่ากันได้ และ maxAttempts จำกัดจำนวนรอบเพิ่มเติมที่โฮสต์จะอนุญาตก่อนดำเนินต่อด้วยคำตอบสุดท้ายตามธรรมชาติ

Plugin ที่ไม่ได้รวมมาพร้อมชุดซึ่งต้องใช้ฮุกการสนทนาแบบดิบ (before_model_resolve, before_agent_reply, llm_input, llm_output, before_agent_finalize, agent_end หรือ before_agent_run) ต้องตั้งค่า:

{
  "plugins": {
    "entries": {
      "my-plugin": {
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}

ฮุกที่แก้ไขพรอมป์และการฉีดข้อมูลถาวรสำหรับเทิร์นถัดไปสามารถปิดใช้งานแยกตาม Plugin ได้ด้วย plugins.entries.<id>.hooks.allowPromptInjection=false

ส่วนขยายเซสชันและการฉีดข้อมูลสำหรับเทิร์นถัดไป

Plugin เวิร์กโฟลว์สามารถเก็บสถานะเซสชันขนาดเล็กที่เข้ากันได้กับ JSON ด้วย api.registerSessionExtension(...) และอัปเดตผ่านเมธอด Gateway sessions.pluginPatch แถวเซสชันจะแสดงสถานะส่วนขยายที่ลงทะเบียนไว้ผ่าน pluginExtensions ทำให้ Control UI และไคลเอนต์อื่นๆ แสดงสถานะที่ Plugin เป็นเจ้าของได้โดยไม่ต้องรู้รายละเอียดภายในของ Plugin

ใช้ api.enqueueNextTurnInjection(...) เมื่อ Plugin ต้องการให้บริบทถาวรไปถึงเทิร์นโมเดลถัดไปแบบครั้งเดียวพอดี OpenClaw จะระบายการฉีดข้อมูลที่เข้าคิวไว้ก่อนฮุกพรอมป์ ทิ้งการฉีดข้อมูลที่หมดอายุ และลบรายการซ้ำด้วย idempotencyKey ต่อ Plugin นี่คือจุดเชื่อมต่อที่เหมาะสำหรับการกลับมาทำงานต่อหลังการอนุมัติ สรุปนโยบาย เดลตาจากตัวเฝ้าระวังเบื้องหลัง และการดำเนินคำสั่งต่อเนื่องที่ควรมองเห็นได้ต่อโมเดลในเทิร์นถัดไป แต่ไม่ควรกลายเป็นข้อความพรอมป์ระบบถาวร

ความหมายของการล้างข้อมูลเป็นส่วนหนึ่งของสัญญา การล้างส่วนขยายเซสชันและคอลแบ็กการล้างวงจรชีวิตรันไทม์จะได้รับ reset, delete, disable หรือ restart โฮสต์จะลบสถานะส่วนขยายเซสชันถาวรของ Plugin เจ้าของและการฉีดข้อมูลสำหรับเทิร์นถัดไปที่รอดำเนินการสำหรับ reset/delete/disable ส่วน restart จะคงสถานะเซสชันถาวรไว้ ขณะที่คอลแบ็กการล้างข้อมูลเปิดให้ Plugin ปล่อยงานของตัวจัดกำหนดการ บริบทการรัน และทรัพยากรนอกแบนด์อื่นๆ สำหรับรุ่นรันไทม์เดิม

ฮุกข้อความ

ใช้ฮุกข้อความสำหรับการกำหนดเส้นทางระดับช่องทางและนโยบายการส่ง:

message_received: สังเกตเนื้อหาขาเข้า ผู้ส่ง threadId, messageId, senderId ความสัมพันธ์กับการรัน/เซสชันที่เป็นทางเลือก และเมทาดาทา
message_sending: เขียน content ใหม่หรือคืนค่า { cancel: true }
message_sent: สังเกตความสำเร็จหรือความล้มเหลวสุดท้าย

สำหรับการตอบกลับ TTS แบบเสียงเท่านั้น content อาจมีข้อความถอดเสียงพูดที่ซ่อนอยู่ แม้เมื่อเพย์โหลดของช่องทางไม่มีข้อความ/คำบรรยายที่มองเห็นได้ การเขียน content นั้นใหม่จะอัปเดตเฉพาะข้อความถอดเสียงที่ฮุกมองเห็นเท่านั้น และจะไม่ถูกแสดงผลเป็นคำบรรยายสื่อ

บริบทฮุกข้อความเปิดเผยฟิลด์ความสัมพันธ์ที่เสถียรเมื่อมีให้ใช้: ctx.sessionKey, ctx.runId, ctx.messageId, ctx.senderId, ctx.trace, ctx.traceId, ctx.spanId, ctx.parentSpanId และ ctx.callDepth ให้ใช้ฟิลด์ชั้นหนึ่งเหล่านี้ก่อนอ่านเมทาดาทาแบบเดิม

ให้ใช้ฟิลด์ threadId และ replyToId แบบมีชนิดก่อนใช้เมทาดาทาเฉพาะช่องทาง

กฎการตัดสินใจ:

message_sending ที่มี cancel: true เป็นจุดสิ้นสุด
message_sending ที่มี cancel: false จะถือว่าไม่มีการตัดสินใจ
content ที่ถูกเขียนใหม่จะดำเนินต่อไปยังฮุกที่มีลำดับความสำคัญต่ำกว่า เว้นแต่ฮุกภายหลังจะยกเลิกการส่ง

ฮุกการติดตั้ง

before_install ทำงานหลังการสแกนในตัวสำหรับการติดตั้ง Skills และ Plugin คืนค่าข้อค้นพบเพิ่มเติมหรือ { block: true, blockReason } เพื่อหยุดการติดตั้ง

block: true เป็นจุดสิ้นสุด block: false จะถือว่าไม่มีการตัดสินใจ

วงจรชีวิต Gateway

ใช้ gateway_start สำหรับบริการ Plugin ที่ต้องการสถานะที่ Gateway เป็นเจ้าของ บริบทเปิดเผย ctx.config, ctx.workspaceDir และ ctx.getCron?.() สำหรับการตรวจสอบและอัปเดต cron ใช้ gateway_stop เพื่อล้างทรัพยากรที่ทำงานยาวนาน

อย่าพึ่งพาฮุกภายใน gateway:startup สำหรับบริการรันไทม์ที่ Plugin เป็นเจ้าของ

cron_changed จะทำงานสำหรับเหตุการณ์วงจรชีวิต cron ที่ Gateway เป็นเจ้าของ พร้อมเพย์โหลดเหตุการณ์แบบมีชนิดที่ครอบคลุมเหตุผล added, updated, removed, started, finished และ scheduled เหตุการณ์จะพกสแนปชอต PluginHookGatewayCronJob (รวมถึง state.nextRunAtMs, state.lastRunStatus และ state.lastError เมื่อมี) พร้อม PluginHookGatewayCronDeliveryStatus เป็น not-requested | delivered | not-delivered | unknown เหตุการณ์ removed ยังคงพกสแนปชอตงานที่ถูกลบ เพื่อให้ตัวจัดกำหนดการภายนอกสามารถปรับสถานะให้ตรงกันได้ ใช้ ctx.getCron?.() และ ctx.config จากบริบทรันไทม์เมื่อซิงค์ตัวจัดกำหนดการปลุกภายนอก และให้ OpenClaw เป็นแหล่งความจริงสำหรับการตรวจสอบกำหนดถึงเวลาและการดำเนินการ

การเลิกใช้งานที่กำลังจะมาถึง

พื้นผิวบางส่วนที่อยู่ใกล้กับฮุกถูกเลิกใช้แล้วแต่ยังรองรับอยู่ ให้ย้ายก่อนรุ่นหลักถัดไป:

ซองช่องทางข้อความธรรมดา ในตัวจัดการ inbound_claim และ message_received ให้อ่าน BodyForAgent และบล็อกบริบทผู้ใช้แบบมีโครงสร้างแทนการแยกวิเคราะห์ข้อความซองแบบแบน ดู ซองช่องทางข้อความธรรมดา → BodyForAgent
before_agent_start ยังคงมีไว้เพื่อความเข้ากันได้ Plugin ใหม่ควรใช้ before_model_resolve และ before_prompt_build แทนเฟสแบบรวม
onResolution ใน before_tool_call ตอนนี้ใช้ยูเนียนแบบมีชนิด PluginApprovalResolution (allow-once / allow-always / deny / timeout / cancelled) แทน string แบบอิสระ

สำหรับรายการเต็ม ได้แก่ การลงทะเบียนความสามารถด้านหน่วยความจำ โปรไฟล์การคิดของผู้ให้บริการ ผู้ให้บริการยืนยันตัวตนภายนอก ชนิดการค้นหาผู้ให้บริการ ตัวเข้าถึงรันไทม์งาน และการเปลี่ยนชื่อ command-auth → command-status โปรดดู การย้าย Plugin SDK → การเลิกใช้งานที่ยังใช้งานอยู่

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

การย้าย Plugin SDK - การเลิกใช้งานที่ยังใช้งานอยู่และไทม์ไลน์การนำออก
การสร้าง Plugin
ภาพรวม Plugin SDK
จุดเข้าใช้งาน Plugin
ฮุกภายใน
รายละเอียดภายในสถาปัตยกรรม Plugin

# เริ่มต้นอย่างรวดเร็ว

# แค็ตตาล็อก Hook

# นโยบายการเรียกเครื่องมือ

# การคงอยู่ของผลลัพธ์เครื่องมือ

# Hook ของพร้อมท์และโมเดล

# ส่วนขยายเซสชันและการฉีดข้อมูลสำหรับเทิร์นถัดไป

# ฮุกข้อความ

# ฮุกการติดตั้ง

# วงจรชีวิต Gateway

# การเลิกใช้งานที่กำลังจะมาถึง

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