Skip to main content

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.

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

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

# List available hooks
openclaw hooks list

# Enable a hook
openclaw hooks enable session-memory

# Check hook status
openclaw hooks check

# Get detailed information
openclaw hooks info session-memory

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

เหตุการณ์เมื่อใดที่เกิดขึ้น
command:newมีการออกคำสั่ง /new
command:resetมีการออกคำสั่ง /reset
command:stopมีการออกคำสั่ง /stop
commandเหตุการณ์คำสั่งใดๆ (ตัวฟังทั่วไป)
session:compact:beforeก่อนที่ Compaction จะสรุปประวัติ
session:compact:afterหลังจาก Compaction เสร็จสมบูรณ์
session:patchเมื่อมีการแก้ไขคุณสมบัติเซสชัน
agent:bootstrapก่อนแทรกไฟล์บูตสแตรปของเวิร์กสเปซ
gateway:startupหลังจากช่องทางเริ่มทำงานและโหลดฮุกแล้ว
gateway:shutdownเมื่อการปิด Gateway เริ่มขึ้น
gateway:pre-restartก่อนการรีสตาร์ท Gateway ที่คาดไว้
message:receivedข้อความขาเข้าจากช่องทางใดๆ
message:transcribedหลังจากการถอดเสียงเสร็จสมบูรณ์
message:preprocessedหลังจากการประมวลผลสื่อและลิงก์ล่วงหน้าเสร็จสิ้นหรือถูกข้าม
message:sentส่งข้อความขาออกแล้ว

การเขียนฮุก

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

ฮุกแต่ละตัวคือไดเรกทอรีที่มีสองไฟล์:
my-hook/
├── HOOK.md          # Metadata + documentation
└── handler.ts       # Handler implementation

รูปแบบ HOOK.md

---
name: my-hook
description: "Short description of what this hook does"
metadata:
  { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } }
---

# My Hook

Detailed documentation goes here.
ฟิลด์เมทาดาทา (metadata.openclaw):
ฟิลด์คำอธิบาย
emojiอีโมจิที่แสดงสำหรับ CLI
eventsอาร์เรย์ของเหตุการณ์ที่จะฟัง
exportNamed export ที่จะใช้ (ค่าเริ่มต้นคือ "default")
osแพลตฟอร์มที่ต้องใช้ (เช่น ["darwin", "linux"])
requiresพาธ bins, anyBins, env, หรือ config ที่ต้องใช้
alwaysข้ามการตรวจสอบสิทธิ์ความพร้อมใช้งาน (บูลีน)
installวิธีการติดตั้ง

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

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 จะถูกปฏิเสธ

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

ฮุกเหตุการณ์สิ่งที่ทำ
session-memorycommand:new, command:resetบันทึกบริบทเซสชันไปยัง <workspace>/memory/
bootstrap-extra-filesagent:bootstrapแทรกไฟล์บูตสแตรปเพิ่มเติมจากรูปแบบ glob
command-loggercommandบันทึกคำสั่งทั้งหมดไปยัง ~/.openclaw/logs/commands.log
compaction-notifiersession:compact:before, session:compact:afterส่งประกาศแชตที่มองเห็นได้เมื่อ Compaction ของเซสชันเริ่ม/จบ
boot-mdgateway:startupเรียกใช้ BOOT.md เมื่อ Gateway เริ่มทำงาน
เปิดใช้งานฮุกที่รวมมาให้ตัวใดก็ได้:
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"]
      }
    }
  }
}
รูปแบบการกำหนดค่าอาร์เรย์ hooks.internal.handlers แบบเดิมยังคงรองรับเพื่อความเข้ากันได้ย้อนหลัง แต่ hooks ใหม่ควรใช้ระบบที่อิงตามการค้นพบ

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

# List all hooks (add --eligible, --verbose, or --json)
openclaw hooks list

# Show detailed info about a hook
openclaw hooks info <hook-name>

# Show eligibility summary
openclaw hooks check

# Enable/disable
openclaw 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 structure
ls -la ~/.openclaw/hooks/my-hook/
# Should show: HOOK.md, handler.ts

# List all discovered hooks
openclaw 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

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