ฮุก

ฮุกคือสคริปต์ขนาดเล็กที่ทำงานเมื่อมีบางอย่างเกิดขึ้นภายใน Gateway โดยสามารถค้นพบได้จากไดเรกทอรีและตรวจสอบด้วย openclaw hooks Gateway จะโหลดฮุกภายในหลังจากที่คุณเปิดใช้งานฮุกหรือกำหนดค่าอย่างน้อยหนึ่งรายการของฮุก, แพ็กฮุก, ตัวจัดการแบบเดิม, หรือไดเรกทอรีฮุกเพิ่มเติมเท่านั้น

ฮุกใน OpenClaw มีสองประเภท:

• ฮุกภายใน (หน้านี้): ทำงานภายใน Gateway เมื่อเหตุการณ์ของเอเจนต์เกิดขึ้น เช่น /new, /reset, /stop, หรือเหตุการณ์วงจรชีวิต
• Webhook: ปลายทาง HTTP ภายนอกที่ให้ระบบอื่นทริกเกอร์งานใน OpenClaw ได้ ดู Webhook

ฮุกยังสามารถรวมมากับ Plugin ได้ด้วย openclaw hooks list จะแสดงทั้งฮุกแบบสแตนด์อโลนและฮุกที่จัดการโดย Plugin

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

# List available hooksopenclaw hooks list # Enable a hookopenclaw hooks enable session-memory # Check hook statusopenclaw hooks check # Get detailed informationopenclaw hooks info session-memory

ประเภทเหตุการณ์

การเขียนฮุก

โครงสร้างฮุก

ฮุกแต่ละตัวคือไดเรกทอรีที่มีสองไฟล์:

my-hook/├── HOOK.md          # Metadata + documentation└── handler.ts       # Handler implementation

รูปแบบ HOOK.md

---name: my-hookdescription: "Short description of what this hook does"metadata:  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }--- # My Hook Detailed documentation goes here.

ฟิลด์เมทาดาทา (metadata.openclaw):

การติดตั้งใช้งานตัวจัดการ

const handler = async (event) => {  if (event.type !== "command" || event.action !== "new") {    return;  }   console.log(`[my-hook] New command triggered`);  // Your logic here   // Optionally send message to user  event.messages.push("Hook executed!");}; export default handler;

แต่ละเหตุการณ์ประกอบด้วย: type, action, sessionKey, timestamp, messages (push เพื่อส่งให้ผู้ใช้), และ context (ข้อมูลเฉพาะเหตุการณ์) บริบทฮุกของเอเจนต์และเครื่องมือ Plugin ยังสามารถมี trace ซึ่งเป็นบริบทการติดตามวินิจฉัยแบบอ่านอย่างเดียวที่เข้ากันได้กับ W3C และ Plugin อาจส่งต่อเข้าไปในล็อกแบบมีโครงสร้างเพื่อเชื่อมโยงกับ OTEL ได้

จุดสำคัญของบริบทเหตุการณ์

เหตุการณ์คำสั่ง (command:new, command:reset): context.sessionEntry, context.previousSessionEntry, context.commandSource, context.workspaceDir, context.cfg

เหตุการณ์ข้อความ (message:received): context.from, context.content, context.channelId, context.metadata (ข้อมูลเฉพาะผู้ให้บริการ รวมถึง senderId, senderName, guildId) context.content จะให้ความสำคัญกับเนื้อหาคำสั่งที่ไม่ว่างสำหรับข้อความที่คล้ายคำสั่ง จากนั้นจึงย้อนกลับไปใช้เนื้อหาขาเข้าแบบดิบและเนื้อหาทั่วไป โดยไม่รวมการเพิ่มข้อมูลเฉพาะเอเจนต์ เช่น ประวัติเธรดหรือสรุปลิงก์

เหตุการณ์ข้อความ (message:sent): context.to, context.content, context.success, context.channelId

เหตุการณ์ข้อความ (message:transcribed): context.transcript, context.from, context.channelId, context.mediaPath

เหตุการณ์ข้อความ (message:preprocessed): context.bodyForAgent (เนื้อหาสุดท้ายที่เพิ่มข้อมูลแล้ว), context.from, context.channelId

เหตุการณ์บูตสแตรป (agent:bootstrap): context.bootstrapFiles (อาร์เรย์ที่แก้ไขได้), context.agentId

เหตุการณ์แพตช์เซสชัน (session:patch): context.sessionEntry, context.patch (เฉพาะฟิลด์ที่เปลี่ยนแปลง), context.cfg เฉพาะไคลเอนต์ที่มีสิทธิ์พิเศษเท่านั้นที่ทริกเกอร์เหตุการณ์แพตช์ได้

เหตุการณ์ Compaction: session:compact:before มี messageCount, tokenCount session:compact:after เพิ่ม compactedCount, summaryLength, tokensBefore, tokensAfter

command:stop สังเกตการที่ผู้ใช้ออกคำสั่ง /stop; เป็นวงจรชีวิตของการยกเลิก/คำสั่ง ไม่ใช่ด่านสำหรับการจบงานของเอเจนต์ Plugin ที่ต้องตรวจสอบคำตอบสุดท้ายตามธรรมชาติ และขอให้เอเจนต์ดำเนินการอีกหนึ่งรอบควรใช้ฮุก Plugin แบบระบุชนิด before_agent_finalize แทน ดู ฮุก Plugin

เหตุการณ์วงจรชีวิต Gateway: gateway:shutdown มี reason และ restartExpectedMs และเกิดขึ้นเมื่อการปิด Gateway เริ่มต้น gateway:pre-restart มีบริบทเดียวกันแต่เกิดขึ้นเฉพาะเมื่อการปิดเป็นส่วนหนึ่งของการรีสตาร์ทที่คาดไว้และมีการระบุค่า restartExpectedMs ที่จำกัด ระหว่างการปิด การรอฮุกวงจรชีวิตแต่ละตัวเป็นแบบพยายามให้ดีที่สุดและมีขอบเขต เพื่อให้การปิดดำเนินต่อไปได้หากตัวจัดการหยุดค้าง

ระหว่างเหตุการณ์ gateway:shutdown (หรือ gateway:pre-restart) กับลำดับการปิดส่วนที่เหลือ Gateway ยังเรียกฮุก Plugin แบบระบุชนิด session_end สำหรับทุกเซสชันที่ยังคงทำงานอยู่เมื่อโปรเซสหยุด ค่า reason ของเหตุการณ์คือ shutdown สำหรับการหยุด SIGTERM/SIGINT ทั่วไป และ restart เมื่อการปิดถูกกำหนดเวลาไว้เป็นส่วนหนึ่งของการรีสตาร์ทที่คาดไว้ การระบายนี้มีขอบเขตเพื่อให้ตัวจัดการ session_end ที่ช้าไม่สามารถบล็อกการออกจากโปรเซสได้ และเซสชันที่ถูกจบไปแล้วผ่าน replace / reset / delete / compaction จะถูกข้ามเพื่อหลีกเลี่ยงการเรียกซ้ำ

การค้นพบฮุก

ฮุกจะถูกค้นพบจากไดเรกทอรีเหล่านี้ ตามลำดับความสำคัญการแทนที่จากน้อยไปมาก:

1. ฮุกที่รวมมาให้: จัดส่งมากับ OpenClaw
2. ฮุก Plugin: ฮุกที่รวมอยู่ภายใน Plugin ที่ติดตั้งไว้
3. ฮุกที่จัดการไว้: ~/.openclaw/hooks/ (ติดตั้งโดยผู้ใช้ ใช้ร่วมกันข้ามเวิร์กสเปซ) ไดเรกทอรีเพิ่มเติมจาก hooks.internal.load.extraDirs ใช้ความสำคัญระดับนี้ร่วมกัน
4. ฮุกของเวิร์กสเปซ: <workspace>/hooks/ (ต่อเอเจนต์ ปิดใช้งานโดยค่าเริ่มต้นจนกว่าจะเปิดใช้งานอย่างชัดเจน)

ฮุกของเวิร์กสเปซสามารถเพิ่มชื่อฮุกใหม่ได้ แต่ไม่สามารถแทนที่ฮุกที่รวมมาให้ ฮุกที่จัดการไว้ หรือฮุกจาก Plugin ที่มีชื่อเดียวกันได้

Gateway จะข้ามการค้นพบฮุกภายในตอนเริ่มต้นจนกว่าจะมีการกำหนดค่าฮุกภายใน เปิดใช้งานฮุกที่รวมมาให้หรือฮุกที่จัดการไว้ด้วย openclaw hooks enable <name> ติดตั้งแพ็กฮุก หรือกำหนด hooks.internal.enabled=true เพื่อเลือกใช้ เมื่อคุณเปิดใช้งานฮุกที่มีชื่อหนึ่งตัว Gateway จะโหลดเฉพาะตัวจัดการของฮุกนั้น; hooks.internal.enabled=true, ไดเรกทอรีฮุกเพิ่มเติม, และตัวจัดการแบบเดิมจะเลือกใช้การค้นพบแบบกว้าง

แพ็กฮุก

แพ็กฮุกคือแพ็กเกจ npm ที่ส่งออกฮุกผ่าน openclaw.hooks ใน package.json ติดตั้งด้วย:

openclaw plugins install <path-or-spec>

สเปก npm รองรับเฉพาะรีจิสทรี (ชื่อแพ็กเกจ + เวอร์ชันแบบระบุแน่นอนหรือ dist-tag ที่เป็นทางเลือก) สเปก Git/URL/file และช่วง semver จะถูกปฏิเสธ

ฮุกที่รวมมาให้

เปิดใช้งานฮุกที่รวมมาให้ตัวใดก็ได้:

openclaw hooks enable <hook-name>

รายละเอียด session-memory

ดึงข้อความผู้ใช้/ผู้ช่วยล่าสุด 15 ข้อความและบันทึกไปยัง <workspace>/memory/YYYY-MM-DD-HHMM.md โดยใช้วันที่ท้องถิ่นของโฮสต์ การจับหน่วยความจำทำงานในเบื้องหลัง ดังนั้นการตอบรับ /new และ /reset จะไม่ถูกหน่วงโดยการอ่านทรานสคริปต์หรือการสร้าง slug ที่เป็นทางเลือก ตั้งค่า hooks.internal.entries.session-memory.llmSlug: true เพื่อสร้าง slug ชื่อไฟล์เชิงบรรยายด้วยโมเดลที่กำหนดค่าไว้ ต้องมีการกำหนดค่า workspace.dir

การกำหนดค่า bootstrap-extra-files

{  "hooks": {    "internal": {      "entries": {        "bootstrap-extra-files": {          "enabled": true,          "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"]        }      }    }  }}

พาธจะถูก resolve โดยอิงกับเวิร์กสเปซ โหลดเฉพาะชื่อฐานของบูตสแตรปที่รู้จักเท่านั้น (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md, MEMORY.md)

รายละเอียด command-logger

บันทึกคำสั่งสแลชทุกคำสั่งไปยัง ~/.openclaw/logs/commands.log

รายละเอียด compaction-notifier

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

รายละเอียด boot-md

เรียกใช้ BOOT.md จากเวิร์กสเปซที่ใช้งานอยู่เมื่อ Gateway เริ่มทำงาน

ฮุก Plugin

Plugin สามารถลงทะเบียนฮุกแบบระบุชนิดผ่าน Plugin SDK เพื่อการผสานรวมที่ลึกขึ้น: การสกัดกั้นการเรียกเครื่องมือ การแก้ไขพรอมต์ การควบคุมโฟลว์ข้อความ และอื่นๆ ใช้ฮุก Plugin เมื่อคุณต้องการ before_tool_call, before_agent_reply, before_install, หรือฮุกวงจรชีวิตอื่นๆ ในโปรเซส

สำหรับข้อมูลอ้างอิงฮุก Plugin ฉบับสมบูรณ์ ดู ฮุก Plugin

การกำหนดค่า

{  "hooks": {    "internal": {      "enabled": true,      "entries": {        "session-memory": { "enabled": true },        "command-logger": { "enabled": false }      }    }  }}

ตัวแปรสภาพแวดล้อมต่อฮุก:

{  "hooks": {    "internal": {      "entries": {        "my-hook": {          "enabled": true,          "env": { "MY_CUSTOM_VAR": "value" }        }      }    }  }}

ไดเรกทอรีฮุกเพิ่มเติม:

{  "hooks": {    "internal": {      "load": {        "extraDirs": ["/path/to/more/hooks"]      }    }  }}

ข้อมูลอ้างอิง CLI

# List all hooks (add --eligible, --verbose, or --json)openclaw hooks list # Show detailed info about a hookopenclaw hooks info <hook-name> # Show eligibility summaryopenclaw hooks check # Enable/disableopenclaw hooks enable <hook-name>openclaw hooks disable <hook-name>

แนวทางปฏิบัติที่แนะนำ

• ทำให้ handlers ทำงานรวดเร็ว Hooks จะทำงานระหว่างการประมวลผลคำสั่ง ส่งงานหนักให้ทำแบบ fire-and-forget ด้วย void processInBackground(event)
• จัดการข้อผิดพลาดอย่างเหมาะสม ครอบการดำเนินการที่มีความเสี่ยงด้วย try/catch; อย่า throw เพื่อให้ handlers อื่นยังทำงานได้
• กรองเหตุการณ์ตั้งแต่ต้น return ทันทีหากประเภท/การกระทำของเหตุการณ์ไม่เกี่ยวข้อง
• ใช้คีย์เหตุการณ์ที่เฉพาะเจาะจง ควรใช้ "events": ["command:new"] แทน "events": ["command"] เพื่อลดภาระงาน

การแก้ไขปัญหา

ไม่พบ hook

# Verify directory structurels -la ~/.openclaw/hooks/my-hook/# Should show: HOOK.md, handler.ts # List all discovered hooksopenclaw hooks list

hook ไม่มีสิทธิ์ใช้งาน

openclaw hooks info my-hook

ตรวจสอบไบนารีที่ขาดหายไป (PATH), ตัวแปรสภาพแวดล้อม, ค่าการกำหนดค่า หรือความเข้ากันได้ของ OS

hook ไม่ทำงาน

1. ตรวจสอบว่า hook เปิดใช้งานอยู่: openclaw hooks list
2. รีสตาร์ทกระบวนการ gateway ของคุณเพื่อให้ hooks โหลดใหม่
3. ตรวจสอบบันทึก gateway: ./scripts/clawlog.sh | grep hook

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

• ข้อมูลอ้างอิง CLI: hooks
• Webhook
• hooks ของ Plugin — hooks วงจรชีวิต Plugin แบบ in-process
• การกำหนดค่า