ฮุกของ 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.

​

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

import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";

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 },
    );
  },
});

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

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

​

แค็ตตาล็อก hook

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

• model_call_started / model_call_ended - สังเกต metadata การเรียก provider/model ที่ผ่านการทำให้ปลอดภัยแล้ว, เวลา, ผลลัพธ์, และแฮช request-id แบบจำกัด โดยไม่มีเนื้อหา prompt หรือ response
• llm_input - สังเกต input ของ provider (system prompt, prompt, ประวัติ)
• llm_output - สังเกต output ของ provider

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

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

• session_start / session_end - ติดตามขอบเขตวงจรชีวิตของเซสชัน reason ของเหตุการณ์เป็นหนึ่งใน new, reset, idle, daily, compaction, deleted, shutdown, restart, หรือ unknown ค่า shutdown และ restart จะทำงานจาก finalizer การปิด Gateway เมื่อโปรเซสถูกหยุดหรือเริ่มใหม่ขณะที่เซสชันยังทำงานอยู่ เพื่อให้ Plugin downstream (เช่น memory หรือ transcript stores) สามารถ finalize แถว ghost ที่อาจค้างอยู่ในสถานะเปิดข้ามการ restart ได้ finalizer ถูกจำกัดเวลาเพื่อไม่ให้ Plugin ที่ช้าบล็อก SIGTERM/SIGINT
• before_compaction / after_compaction - สังเกตหรือ annotate รอบ Compaction
• before_reset - สังเกตเหตุการณ์รีเซ็ตเซสชัน (/reset, การรีเซ็ตแบบ programmatic)

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

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

​

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

• event.toolName
• event.params
• event.derivedPaths แบบไม่บังคับ ซึ่งมี hint เส้นทางเป้าหมายที่ host derive แบบ best-effort สำหรับ envelope ของเครื่องมือที่รู้จักดี เช่น apply_patch; เมื่อมีอยู่ เส้นทางเหล่านี้อาจไม่สมบูรณ์หรืออาจประเมินเกินสิ่งที่เครื่องมือจะ แตะจริง (เช่น input ที่ผิดรูปแบบหรือไม่ครบถ้วน)
• 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 เป็น terminal และข้ามตัวจัดการที่มี priority ต่ำกว่า
• block: false ถือว่าไม่มีการตัดสินใจ
• params เขียนพารามิเตอร์เครื่องมือใหม่สำหรับการดำเนินการ
• requireApproval หยุดการรันของเอเจนต์ชั่วคราวและถามผู้ใช้ผ่านการอนุมัติของ Plugin คำสั่ง /approve สามารถอนุมัติได้ทั้ง exec และการอนุมัติของ Plugin
• block: true ที่มี priority ต่ำกว่ายังสามารถบล็อกได้หลัง hook ที่มี priority สูงกว่า ขออนุมัติแล้ว
• onResolution ได้รับการตัดสินใจอนุมัติที่ resolve แล้ว - allow-once, allow-always, deny, timeout, หรือ cancelled

​

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

• OpenClaw ลบ toolResult.details ก่อน replay ให้ provider และก่อน input ของ Compaction เพื่อไม่ให้ metadata กลายเป็นบริบทของโมเดล
• รายการเซสชันที่คงอยู่จะเก็บเฉพาะ details แบบจำกัด ข้อมูลรายละเอียดที่ใหญ่เกินไปจะ ถูกแทนที่ด้วยสรุปแบบกะทัดรัดและ persistedDetailsTruncated: true
• tool_result_persist และ before_message_write ทำงานก่อน cap การคงอยู่สุดท้าย hook ยังควรรักษา details ที่ return ให้มีขนาดเล็ก และหลีกเลี่ยงการ วางข้อความที่เกี่ยวข้องกับ prompt ไว้เฉพาะใน details; ให้วาง output ของเครื่องมือที่โมเดลเห็นได้ ใน content

​

hook ของ prompt และโมเดล

• before_model_resolve: รับเฉพาะ prompt ปัจจุบันและ metadata ของ attachment return providerOverride หรือ modelOverride
• agent_turn_prepare: รับ prompt ปัจจุบัน, ข้อความเซสชันที่เตรียมไว้, และการฉีดที่เข้าคิวแบบ exactly-once ใดๆ ที่ drain สำหรับเซสชันนี้ return prependContext หรือ appendContext
• before_prompt_build: รับ prompt ปัจจุบันและข้อความเซสชัน return prependContext, appendContext, systemPrompt, prependSystemContext, หรือ appendSystemContext
• heartbeat_prompt_contribution: ทำงานเฉพาะรอบ Heartbeat และ return prependContext หรือ appendContext มีไว้สำหรับ monitor เบื้องหลัง ที่ต้องสรุปสถานะปัจจุบันโดยไม่เปลี่ยนรอบการทำงานที่ผู้ใช้เริ่ม

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

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

​

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

​

Hook ข้อความ

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

• message_sending ที่มี cancel: true ถือเป็นจุดสิ้นสุด
• message_sending ที่มี cancel: false ถือว่าไม่มีการตัดสินใจ
• content ที่ถูกเขียนใหม่จะส่งต่อไปยัง Hook ลำดับความสำคัญต่ำกว่าต่อไป เว้นแต่ Hook ถัดไป จะยกเลิกการส่งมอบ
• message_sending สามารถคืน cancelReason และ metadata แบบมีขอบเขตพร้อม การยกเลิกได้ API วงจรชีวิตข้อความใหม่เปิดเผยสิ่งนี้เป็นผลลัพธ์การส่งมอบที่ถูกระงับ พร้อมเหตุผล cancelled_by_message_sending_hook; การส่งมอบโดยตรงแบบเก่า ยังคงคืนอาร์เรย์ผลลัพธ์ว่างเพื่อความเข้ากันได้
• message_sent ใช้เพื่อสังเกตเท่านั้น ความล้มเหลวของตัวจัดการจะถูกบันทึกและไม่ เปลี่ยนผลลัพธ์การส่งมอบ

​

Hook การติดตั้ง

​

วงจรชีวิต Gateway

​

รายการที่จะเลิกใช้งานเร็วๆ นี้

• ซองช่องทางข้อความล้วน ในตัวจัดการ 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 แบบอิสระ

​

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

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